@logtape/file 1.0.5 → 1.0.6

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/file",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "license": "MIT",
   "exports": "./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 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.
+ * @typeParam TFile The type of the file descriptor.
+ */
+
+/**
+ * Get a platform-independent file sink.
+ *
+ * @typeParam 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 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 * @typeParam 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 * @typeParam 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 * @typeParam 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 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
 */
@@ -71,11 +72,17 @@ function getStreamFileSink(path, options = {}) {
 		if (disposed) return;
 		passThrough.write(formatter(record));
 	};
-	sink[Symbol.dispose] = () => {
+	sink[Symbol.asyncDispose] = async () => {
 		if (disposed) return;
 		disposed = true;
 		passThrough.end();
-		writeStream.end();
+		await new Promise((resolve) => {
+			writeStream.once("finish", () => {
+				writeStream.close(() => {
+					resolve();
+				});
+			});
+		});
 	};
 	return sink;
 }

package/dist/streamfilesink.d.cts

@@ -84,11 +84,12 @@ 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
  */
-declare function getStreamFileSink(path: string, options?: StreamFileSinkOptions): Sink & Disposable;
+declare function getStreamFileSink(path: string, options?: StreamFileSinkOptions): Sink & AsyncDisposable;
 //# sourceMappingURL=streamfilesink.d.ts.map
 //#endregion
 export { StreamFileSinkOptions, getStreamFileSink };

package/dist/streamfilesink.d.cts.map

@@ -1 +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"}
+{"version":3,"file":"streamfilesink.d.cts","names":[],"sources":["../streamfilesink.ts"],"sourcesContent":[],"mappings":";;;;;;AAkBA;AAgFA;;;;;AAGyB;UAnFR,qBAAA;;;;;;;;;;;;;;;;;;;;;;uBAuBM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyDP,iBAAA,yBAEL,wBACR,OAAO"}

package/dist/streamfilesink.d.ts

@@ -84,11 +84,12 @@ 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
  */
-declare function getStreamFileSink(path: string, options?: StreamFileSinkOptions): Sink & Disposable;
+declare function getStreamFileSink(path: string, options?: StreamFileSinkOptions): Sink & AsyncDisposable;
 //# sourceMappingURL=streamfilesink.d.ts.map
 //#endregion
 export { StreamFileSinkOptions, getStreamFileSink };

package/dist/streamfilesink.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"streamfilesink.d.ts","names":[],"sources":["../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
 */
@@ -70,11 +71,17 @@ function getStreamFileSink(path, options = {}) {
 		if (disposed) return;
 		passThrough.write(formatter(record));
 	};
-	sink[Symbol.dispose] = () => {
+	sink[Symbol.asyncDispose] = async () => {
 		if (disposed) return;
 		disposed = true;
 		passThrough.end();
-		writeStream.end();
+		await new Promise((resolve) => {
+			writeStream.once("finish", () => {
+				writeStream.close(() => {
+					resolve();
+				});
+			});
+		});
 	};
 	return sink;
 }

package/dist/streamfilesink.js.map

@@ -1 +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"}
+{"version":3,"file":"streamfilesink.js","names":["path: string","options: StreamFileSinkOptions","sink: Sink & AsyncDisposable","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 `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  // Async disposal that waits for streams to finish\n  sink[Symbol.asyncDispose] = async () => {\n    if (disposed) return;\n    disposed = true;\n\n    // End the PassThrough stream\n    passThrough.end();\n\n    // Wait for both finish (data flushed) and close (file handle closed) events\n    await new Promise<void>((resolve) => {\n      writeStream.once(\"finish\", () => {\n        writeStream.close(() => {\n          resolve();\n        });\n      });\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,cAAY,KAAK;AAGjB,QAAM,IAAI,QAAc,CAAC,YAAY;AACnC,eAAY,KAAK,UAAU,MAAM;AAC/B,gBAAY,MAAM,MAAM;AACtB,cAAS;IACV,EAAC;GACH,EAAC;EACH;CACF;AAED,QAAO;AACR"}

package/package.json

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

package/streamfilesink.test.ts

@@ -1,12 +1,12 @@
 import { getStreamFileSink } from "./streamfilesink.ts";
 import { suite } from "@alinea/suite";
-import type { LogRecord, Sink } from "@logtape/logtape";
+import type { LogRecord } 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 { platform, tmpdir } from "node:os";
+import { tmpdir } from "node:os";
 import { debug, error, fatal, info, warning } from "../logtape/fixtures.ts";
 
 const test = suite(import.meta);
@@ -17,7 +17,7 @@ function makeTempFileSync(): string {
 
 test("getStreamFileSink() basic functionality", async () => {
   const path = makeTempFileSync();
-  const sink: Sink & Disposable = getStreamFileSink(path);
+  const sink = getStreamFileSink(path);
 
   sink(debug);
   sink(info);
@@ -25,10 +25,7 @@ test("getStreamFileSink() basic functionality", async () => {
   sink(error);
   sink(fatal);
 
-  sink[Symbol.dispose]();
-
-  // Allow stream to fully flush
-  await delay(50);
+  await sink[Symbol.asyncDispose]();
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   assertEquals(
@@ -47,9 +44,7 @@ test("getStreamFileSink() with custom highWaterMark", async () => {
 
   sink(debug);
   sink(info);
-  sink[Symbol.dispose]();
-
-  await delay(50);
+  await sink[Symbol.asyncDispose]();
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   assertEquals(
@@ -67,9 +62,7 @@ test("getStreamFileSink() with custom formatter", async () => {
 
   sink(debug);
   sink(info);
-  sink[Symbol.dispose]();
-
-  await delay(50);
+  await sink[Symbol.asyncDispose]();
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   assertEquals(
@@ -87,9 +80,7 @@ test("getStreamFileSink() appends to existing file", async () => {
 
   const sink = getStreamFileSink(path);
   sink(debug);
-  sink[Symbol.dispose]();
-
-  await delay(50);
+  await sink[Symbol.asyncDispose]();
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   assert(content.startsWith("Initial content\n"));
@@ -109,8 +100,7 @@ test("getStreamFileSink() high-volume logging", async () => {
     sink(record);
   }
 
-  sink[Symbol.dispose]();
-  await delay(100); // Allow streams to finish
+  await sink[Symbol.asyncDispose]();
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   const lines = content.split("\n").filter((line) => line.length > 0);
@@ -126,14 +116,12 @@ test("getStreamFileSink() disposal stops writing", async () => {
   const sink = getStreamFileSink(path);
 
   sink(debug);
-  sink[Symbol.dispose]();
+  await sink[Symbol.asyncDispose]();
 
   // 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
@@ -147,10 +135,8 @@ test("getStreamFileSink() double disposal", async () => {
   const sink = getStreamFileSink(path);
 
   sink(debug);
-  sink[Symbol.dispose]();
-  sink[Symbol.dispose](); // Should not throw
-
-  await delay(50);
+  await sink[Symbol.asyncDispose]();
+  await sink[Symbol.asyncDispose](); // Should not throw
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   const lines = content.split("\n").filter((line) => line.length > 0);
@@ -163,9 +149,7 @@ test("getStreamFileSink() handles rapid disposal", async () => {
 
   sink(debug);
   // Dispose immediately without waiting
-  sink[Symbol.dispose]();
-
-  await delay(50);
+  await sink[Symbol.asyncDispose]();
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   assert(content.includes("Hello, 123 & 456!"));
@@ -193,8 +177,7 @@ test("getStreamFileSink() concurrent writes", async () => {
   }
 
   await Promise.all(promises);
-  sink[Symbol.dispose]();
-  await delay(100);
+  await sink[Symbol.asyncDispose]();
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   const lines = content.split("\n").filter((line) => line.length > 0);
@@ -216,9 +199,7 @@ test("getStreamFileSink() with empty records", async () => {
   };
 
   sink(emptyRecord);
-  sink[Symbol.dispose]();
-
-  await delay(50);
+  await sink[Symbol.asyncDispose]();
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   assert(content.includes("[DBG]"));
@@ -237,9 +218,7 @@ test("getStreamFileSink() with large messages", async () => {
   };
 
   sink(largeRecord);
-  sink[Symbol.dispose]();
-
-  await delay(100); // Give more time for large write
+  await sink[Symbol.asyncDispose]();
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   assert(content.includes(largeMessage));
@@ -264,8 +243,7 @@ test("getStreamFileSink() memory efficiency", async () => {
     }
   }
 
-  sink[Symbol.dispose]();
-  await delay(platform() === "win32" ? 1000 : 200);
+  await sink[Symbol.asyncDispose]();
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   const lines = content.split("\n").filter((line) => line.length > 0);
@@ -283,9 +261,7 @@ test("getStreamFileSink() creates new file when it doesn't exist", async () => {
 
   const sink = getStreamFileSink(path);
   sink(debug);
-  sink[Symbol.dispose]();
-
-  await delay(50);
+  await sink[Symbol.asyncDispose]();
 
   // File should have been created
   assert(fs.existsSync(path));
@@ -302,10 +278,8 @@ test("getStreamFileSink() multiple instances on same file", async () => {
   sink1(debug);
   sink2(info);
 
-  sink1[Symbol.dispose]();
-  sink2[Symbol.dispose]();
-
-  await delay(100);
+  await sink1[Symbol.asyncDispose]();
+  await sink2[Symbol.asyncDispose]();
 
   const content = fs.readFileSync(path, { encoding: "utf-8" });
   assert(content.includes("[DBG]"));
@@ -317,8 +291,7 @@ test("getStreamFileSink() stream error handling", async () => {
   const sink = getStreamFileSink(path);
 
   sink(debug);
-  sink[Symbol.dispose]();
-  await delay(50);
+  await sink[Symbol.asyncDispose]();
 
   // Delete the file after disposal
   try {

package/streamfilesink.ts

@@ -91,14 +91,15 @@ 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
  */
 export function getStreamFileSink(
   path: string,
   options: StreamFileSinkOptions = {},
-): Sink & Disposable {
+): Sink & AsyncDisposable {
   const highWaterMark = options.highWaterMark ?? 16384;
   const formatter = options.formatter ?? defaultTextFormatter;
 
@@ -117,19 +118,29 @@ export function getStreamFileSink(
   let disposed = false;
 
   // Stream-based sink function for high performance
-  const sink: Sink & Disposable = (record: LogRecord) => {
+  const sink: Sink & AsyncDisposable = (record: LogRecord) => {
     if (disposed) return;
 
     // Direct write to PassThrough stream
     passThrough.write(formatter(record));
   };
 
-  // Minimal disposal
-  sink[Symbol.dispose] = () => {
+  // Async disposal that waits for streams to finish
+  sink[Symbol.asyncDispose] = async () => {
     if (disposed) return;
     disposed = true;
+
+    // End the PassThrough stream
     passThrough.end();
-    writeStream.end();
+
+    // Wait for both finish (data flushed) and close (file handle closed) events
+    await new Promise<void>((resolve) => {
+      writeStream.once("finish", () => {
+        writeStream.close(() => {
+          resolve();
+        });
+      });
+    });
   };
 
   return sink;