@logtape/file 0.12.0-dev.194 → 0.12.0-dev.196

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/file",
-  "version": "0.12.0-dev.194+4b7c1127",
+  "version": "0.12.0-dev.196+8684bab0",
   "license": "MIT",
   "exports": "./mod.ts",
   "imports": {

package/dist/filesink.base.cjs

@@ -15,21 +15,29 @@ function getBaseFileSink(path, options) {
 	const formatter = options.formatter ?? __logtape_logtape.defaultTextFormatter;
 	const encoder = options.encoder ?? new TextEncoder();
 	const bufferSize = options.bufferSize ?? 1024 * 8;
+	const flushInterval = options.flushInterval ?? 5e3;
 	let fd = options.lazy ? null : options.openSync(path);
 	let buffer = "";
-	const sink = (record) => {
-		if (fd == null) fd = options.openSync(path);
-		buffer += formatter(record);
-		if (buffer.length >= bufferSize) {
+	let lastFlushTimestamp = Date.now();
+	function flushBuffer() {
+		if (fd == null) return;
+		if (buffer.length > 0) {
 			options.writeSync(fd, encoder.encode(buffer));
 			buffer = "";
 			options.flushSync(fd);
+			lastFlushTimestamp = Date.now();
 		}
+	}
+	const sink = (record) => {
+		if (fd == null) fd = options.openSync(path);
+		buffer += formatter(record);
+		const shouldFlushBySize = buffer.length >= bufferSize;
+		const shouldFlushByTime = flushInterval > 0 && record.timestamp - lastFlushTimestamp >= flushInterval;
+		if (shouldFlushBySize || shouldFlushByTime) flushBuffer();
 	};
 	sink[Symbol.dispose] = () => {
 		if (fd !== null) {
-			options.writeSync(fd, encoder.encode(buffer));
-			options.flushSync(fd);
+			flushBuffer();
 			options.closeSync(fd);
 		}
 	};
@@ -54,12 +62,14 @@ function getBaseRotatingFileSink(path, options) {
 	const maxSize = options.maxSize ?? 1024 * 1024;
 	const maxFiles = options.maxFiles ?? 5;
 	const bufferSize = options.bufferSize ?? 1024 * 8;
+	const flushInterval = options.flushInterval ?? 5e3;
 	let offset = 0;
 	try {
 		const stat = options.statSync(path);
 		offset = stat.size;
 	} catch {}
 	let fd = options.openSync(path);
+	let lastFlushTimestamp = Date.now();
 	function shouldRollover(bytes) {
 		return offset + bytes.length > maxSize;
 	}
@@ -76,21 +86,26 @@ function getBaseRotatingFileSink(path, options) {
 		offset = 0;
 		fd = options.openSync(path);
 	}
-	let buffer = "";
-	const sink = (record) => {
-		buffer += formatter(record);
-		if (buffer.length >= bufferSize) {
+	function flushBuffer() {
+		if (buffer.length > 0) {
 			const bytes = encoder.encode(buffer);
 			buffer = "";
 			if (shouldRollover(bytes)) performRollover();
 			options.writeSync(fd, bytes);
 			options.flushSync(fd);
 			offset += bytes.length;
+			lastFlushTimestamp = Date.now();
 		}
+	}
+	let buffer = "";
+	const sink = (record) => {
+		buffer += formatter(record);
+		const shouldFlushBySize = buffer.length >= bufferSize;
+		const shouldFlushByTime = flushInterval > 0 && record.timestamp - lastFlushTimestamp >= flushInterval;
+		if (shouldFlushBySize || shouldFlushByTime) flushBuffer();
 	};
 	sink[Symbol.dispose] = () => {
-		options.writeSync(fd, encoder.encode(buffer));
-		options.flushSync(fd);
+		flushBuffer();
 		options.closeSync(fd);
 	};
 	return sink;

package/dist/filesink.base.d.cts

@@ -18,6 +18,14 @@ type FileSinkOptions = StreamSinkOptions & {
    * @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;
 };
 /**
  * A platform-specific file sink driver.

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

@@ -1 +1 @@
-{"version":3,"file":"filesink.base.d.cts","names":[],"sources":["../filesink.base.ts"],"sourcesContent":[],"mappings":";;;;;;AAUA;AAoBiB,KApBL,eAAA,GAAkB,iBAoBC,GAAA;EAAA;;;EAYV,IAAS,CAAA,EAAA,OAAA;EAAU;;AAYnB;AA2CrB;;;;EAAqD,UAAA,CAAA,EAAA,MAAA;AAerD,CAAA;;;;AAAqE;UAlFpD;;;;;0BAKS;;;;;;gBAOV,cAAc;;;;;gBAMd;;;;;gBAMA;;;;;;;;;;;;;;;UA2CC,uBAAA,SAAgC,KAAK;;;;;;;;;;;;;UAerC,sCAAsC,eAAe"}
+{"version":3,"file":"filesink.base.d.cts","names":[],"sources":["../filesink.base.ts"],"sourcesContent":[],"mappings":";;;;;;AAUA;AA6BiB,KA7BL,eAAA,GAAkB,iBA6BC,GAAA;EAAA;;;EAYV,IAAS,CAAA,EAAA,OAAA;EAAU;;AAYnB;AA0DrB;;;;EAAqD,UAAA,CAAA,EAAA,MAAA;EAepC;;;;AAAoD;;;;;;;;;UAjGpD;;;;;0BAKS;;;;;;gBAOV,cAAc;;;;;gBAMd;;;;;gBAMA;;;;;;;;;;;;;;;UA0DC,uBAAA,SAAgC,KAAK;;;;;;;;;;;;;UAerC,sCAAsC,eAAe"}

package/dist/filesink.base.d.ts

@@ -18,6 +18,14 @@ type FileSinkOptions = StreamSinkOptions & {
    * @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;
 };
 /**
  * A platform-specific file sink driver.

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

@@ -1 +1 @@
-{"version":3,"file":"filesink.base.d.ts","names":[],"sources":["../filesink.base.ts"],"sourcesContent":[],"mappings":";;;;;;AAUA;AAoBiB,KApBL,eAAA,GAAkB,iBAoBC,GAAA;EAAA;;;EAYV,IAAS,CAAA,EAAA,OAAA;EAAU;;AAYnB;AA2CrB;;;;EAAqD,UAAA,CAAA,EAAA,MAAA;AAerD,CAAA;;;;AAAqE;UAlFpD;;;;;0BAKS;;;;;;gBAOV,cAAc;;;;;gBAMd;;;;;gBAMA;;;;;;;;;;;;;;;UA2CC,uBAAA,SAAgC,KAAK;;;;;;;;;;;;;UAerC,sCAAsC,eAAe"}
+{"version":3,"file":"filesink.base.d.ts","names":[],"sources":["../filesink.base.ts"],"sourcesContent":[],"mappings":";;;;;;AAUA;AA6BiB,KA7BL,eAAA,GAAkB,iBA6BC,GAAA;EAAA;;;EAYV,IAAS,CAAA,EAAA,OAAA;EAAU;;AAYnB;AA0DrB;;;;EAAqD,UAAA,CAAA,EAAA,MAAA;EAepC;;;;AAAoD;;;;;;;;;UAjGpD;;;;;0BAKS;;;;;;gBAOV,cAAc;;;;;gBAMd;;;;;gBAMA;;;;;;;;;;;;;;;UA0DC,uBAAA,SAAgC,KAAK;;;;;;;;;;;;;UAerC,sCAAsC,eAAe"}

package/dist/filesink.base.js

@@ -14,21 +14,29 @@ function getBaseFileSink(path, options) {
 	const formatter = options.formatter ?? defaultTextFormatter;
 	const encoder = options.encoder ?? new TextEncoder();
 	const bufferSize = options.bufferSize ?? 1024 * 8;
+	const flushInterval = options.flushInterval ?? 5e3;
 	let fd = options.lazy ? null : options.openSync(path);
 	let buffer = "";
-	const sink = (record) => {
-		if (fd == null) fd = options.openSync(path);
-		buffer += formatter(record);
-		if (buffer.length >= bufferSize) {
+	let lastFlushTimestamp = Date.now();
+	function flushBuffer() {
+		if (fd == null) return;
+		if (buffer.length > 0) {
 			options.writeSync(fd, encoder.encode(buffer));
 			buffer = "";
 			options.flushSync(fd);
+			lastFlushTimestamp = Date.now();
 		}
+	}
+	const sink = (record) => {
+		if (fd == null) fd = options.openSync(path);
+		buffer += formatter(record);
+		const shouldFlushBySize = buffer.length >= bufferSize;
+		const shouldFlushByTime = flushInterval > 0 && record.timestamp - lastFlushTimestamp >= flushInterval;
+		if (shouldFlushBySize || shouldFlushByTime) flushBuffer();
 	};
 	sink[Symbol.dispose] = () => {
 		if (fd !== null) {
-			options.writeSync(fd, encoder.encode(buffer));
-			options.flushSync(fd);
+			flushBuffer();
 			options.closeSync(fd);
 		}
 	};
@@ -53,12 +61,14 @@ function getBaseRotatingFileSink(path, options) {
 	const maxSize = options.maxSize ?? 1024 * 1024;
 	const maxFiles = options.maxFiles ?? 5;
 	const bufferSize = options.bufferSize ?? 1024 * 8;
+	const flushInterval = options.flushInterval ?? 5e3;
 	let offset = 0;
 	try {
 		const stat = options.statSync(path);
 		offset = stat.size;
 	} catch {}
 	let fd = options.openSync(path);
+	let lastFlushTimestamp = Date.now();
 	function shouldRollover(bytes) {
 		return offset + bytes.length > maxSize;
 	}
@@ -75,21 +85,26 @@ function getBaseRotatingFileSink(path, options) {
 		offset = 0;
 		fd = options.openSync(path);
 	}
-	let buffer = "";
-	const sink = (record) => {
-		buffer += formatter(record);
-		if (buffer.length >= bufferSize) {
+	function flushBuffer() {
+		if (buffer.length > 0) {
 			const bytes = encoder.encode(buffer);
 			buffer = "";
 			if (shouldRollover(bytes)) performRollover();
 			options.writeSync(fd, bytes);
 			options.flushSync(fd);
 			offset += bytes.length;
+			lastFlushTimestamp = Date.now();
 		}
+	}
+	let buffer = "";
+	const sink = (record) => {
+		buffer += formatter(record);
+		const shouldFlushBySize = buffer.length >= bufferSize;
+		const shouldFlushByTime = flushInterval > 0 && record.timestamp - lastFlushTimestamp >= flushInterval;
+		if (shouldFlushBySize || shouldFlushByTime) flushBuffer();
 	};
 	sink[Symbol.dispose] = () => {
-		options.writeSync(fd, encoder.encode(buffer));
-		options.flushSync(fd);
+		flushBuffer();
 		options.closeSync(fd);
 	};
 	return sink;

package/dist/filesink.base.js.map

@@ -1 +1 @@
-{"version":3,"file":"filesink.base.js","names":["path: string","options: FileSinkOptions & FileSinkDriver<TFile>","buffer: string","sink: Sink & Disposable","record: LogRecord","options: RotatingFileSinkOptions & RotatingFileSinkDriver<TFile>","offset: number","bytes: Uint8Array"],"sources":["../filesink.base.ts"],"sourcesContent":["import {\n  defaultTextFormatter,\n  type LogRecord,\n  type Sink,\n  type StreamSinkOptions,\n} from \"@logtape/logtape\";\n\n/**\n * Options for the {@link getBaseFileSink} function.\n */\nexport type FileSinkOptions = StreamSinkOptions & {\n  /**\n   * If `true`, the file is not opened until the first write.  Defaults to `false`.\n   */\n  lazy?: boolean;\n\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\n/**\n * A platform-specific file sink driver.\n * @typeParam TFile The type of the file descriptor.\n */\nexport interface 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  /**\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  /**\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  /**\n   * Close the file.\n   * @param fd The file descriptor.\n   */\n  closeSync(fd: TFile): void;\n}\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.\n */\nexport function getBaseFileSink<TFile>(\n  path: string,\n  options: FileSinkOptions & FileSinkDriver<TFile>,\n): Sink & Disposable {\n  const formatter = options.formatter ?? defaultTextFormatter;\n  const encoder = options.encoder ?? new TextEncoder();\n  const bufferSize = options.bufferSize ?? 1024 * 8; // Default buffer size of 8192 chars\n  let fd = options.lazy ? null : options.openSync(path);\n  let buffer: string = \"\";\n  const sink: Sink & Disposable = (record: LogRecord) => {\n    if (fd == null) fd = options.openSync(path);\n    buffer += formatter(record);\n    if (buffer.length >= bufferSize) {\n      options.writeSync(fd, encoder.encode(buffer));\n      buffer = \"\";\n      options.flushSync(fd);\n    }\n  };\n  sink[Symbol.dispose] = () => {\n    if (fd !== null) {\n      options.writeSync(fd, encoder.encode(buffer));\n      options.flushSync(fd);\n      options.closeSync(fd);\n    }\n  };\n  return sink;\n}\n\n/**\n * Options for the {@link getBaseRotatingFileSink} function.\n */\nexport interface 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  /**\n   * The maximum number of files to keep.  5 by default.\n   */\n  maxFiles?: number;\n}\n\n/**\n * A platform-specific rotating file sink driver.\n */\nexport interface 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): { 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/**\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.\n */\nexport function getBaseRotatingFileSink<TFile>(\n  path: string,\n  options: RotatingFileSinkOptions & RotatingFileSinkDriver<TFile>,\n): Sink & Disposable {\n  const formatter = options.formatter ?? defaultTextFormatter;\n  const encoder = options.encoder ?? new TextEncoder();\n  const maxSize = options.maxSize ?? 1024 * 1024;\n  const maxFiles = options.maxFiles ?? 5;\n  const bufferSize = options.bufferSize ?? 1024 * 8; // Default buffer size of 8192 chars\n  let offset: number = 0;\n  try {\n    const stat = options.statSync(path);\n    offset = stat.size;\n  } catch {\n    // Continue as the offset is already 0.\n  }\n  let fd = options.openSync(path);\n  function shouldRollover(bytes: Uint8Array): boolean {\n    return offset + bytes.length > maxSize;\n  }\n  function performRollover(): void {\n    options.closeSync(fd);\n    for (let i = maxFiles - 1; i > 0; i--) {\n      const oldPath = `${path}.${i}`;\n      const newPath = `${path}.${i + 1}`;\n      try {\n        options.renameSync(oldPath, newPath);\n      } catch (_) {\n        // Continue if the file does not exist.\n      }\n    }\n    options.renameSync(path, `${path}.1`);\n    offset = 0;\n    fd = options.openSync(path);\n  }\n  let buffer: string = \"\";\n  const sink: Sink & Disposable = (record: LogRecord) => {\n    buffer += formatter(record);\n    if (buffer.length >= bufferSize) {\n      const bytes = encoder.encode(buffer);\n      buffer = \"\";\n      if (shouldRollover(bytes)) performRollover();\n      options.writeSync(fd, bytes);\n      options.flushSync(fd);\n      offset += bytes.length;\n    }\n  };\n  sink[Symbol.dispose] = () => {\n    options.writeSync(fd, encoder.encode(buffer));\n    options.flushSync(fd);\n    options.closeSync(fd);\n  };\n  return sink;\n}\n"],"mappings":";;;;;;;;;;;;AAkEA,SAAgB,gBACdA,MACAC,SACmB;CACnB,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,UAAU,QAAQ,WAAW,IAAI;CACvC,MAAM,aAAa,QAAQ,cAAc,OAAO;CAChD,IAAI,KAAK,QAAQ,OAAO,OAAO,QAAQ,SAAS,KAAK;CACrD,IAAIC,SAAiB;CACrB,MAAMC,OAA0B,CAACC,WAAsB;AACrD,MAAI,MAAM,KAAM,MAAK,QAAQ,SAAS,KAAK;AAC3C,YAAU,UAAU,OAAO;AAC3B,MAAI,OAAO,UAAU,YAAY;AAC/B,WAAQ,UAAU,IAAI,QAAQ,OAAO,OAAO,CAAC;AAC7C,YAAS;AACT,WAAQ,UAAU,GAAG;EACtB;CACF;AACD,MAAK,OAAO,WAAW,MAAM;AAC3B,MAAI,OAAO,MAAM;AACf,WAAQ,UAAU,IAAI,QAAQ,OAAO,OAAO,CAAC;AAC7C,WAAQ,UAAU,GAAG;AACrB,WAAQ,UAAU,GAAG;EACtB;CACF;AACD,QAAO;AACR;;;;;;;;;;;;;;AAiDD,SAAgB,wBACdJ,MACAK,SACmB;CACnB,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,UAAU,QAAQ,WAAW,IAAI;CACvC,MAAM,UAAU,QAAQ,WAAW,OAAO;CAC1C,MAAM,WAAW,QAAQ,YAAY;CACrC,MAAM,aAAa,QAAQ,cAAc,OAAO;CAChD,IAAIC,SAAiB;AACrB,KAAI;EACF,MAAM,OAAO,QAAQ,SAAS,KAAK;AACnC,WAAS,KAAK;CACf,QAAO,CAEP;CACD,IAAI,KAAK,QAAQ,SAAS,KAAK;CAC/B,SAAS,eAAeC,OAA4B;AAClD,SAAO,SAAS,MAAM,SAAS;CAChC;CACD,SAAS,kBAAwB;AAC/B,UAAQ,UAAU,GAAG;AACrB,OAAK,IAAI,IAAI,WAAW,GAAG,IAAI,GAAG,KAAK;GACrC,MAAM,WAAW,EAAE,KAAK,GAAG,EAAE;GAC7B,MAAM,WAAW,EAAE,KAAK,GAAG,IAAI,EAAE;AACjC,OAAI;AACF,YAAQ,WAAW,SAAS,QAAQ;GACrC,SAAQ,GAAG,CAEX;EACF;AACD,UAAQ,WAAW,OAAO,EAAE,KAAK,IAAI;AACrC,WAAS;AACT,OAAK,QAAQ,SAAS,KAAK;CAC5B;CACD,IAAIL,SAAiB;CACrB,MAAMC,OAA0B,CAACC,WAAsB;AACrD,YAAU,UAAU,OAAO;AAC3B,MAAI,OAAO,UAAU,YAAY;GAC/B,MAAM,QAAQ,QAAQ,OAAO,OAAO;AACpC,YAAS;AACT,OAAI,eAAe,MAAM,CAAE,kBAAiB;AAC5C,WAAQ,UAAU,IAAI,MAAM;AAC5B,WAAQ,UAAU,GAAG;AACrB,aAAU,MAAM;EACjB;CACF;AACD,MAAK,OAAO,WAAW,MAAM;AAC3B,UAAQ,UAAU,IAAI,QAAQ,OAAO,OAAO,CAAC;AAC7C,UAAQ,UAAU,GAAG;AACrB,UAAQ,UAAU,GAAG;CACtB;AACD,QAAO;AACR"}
+{"version":3,"file":"filesink.base.js","names":["path: string","options: FileSinkOptions & FileSinkDriver<TFile>","buffer: string","lastFlushTimestamp: number","sink: Sink & Disposable","record: LogRecord","options: RotatingFileSinkOptions & RotatingFileSinkDriver<TFile>","offset: number","bytes: Uint8Array"],"sources":["../filesink.base.ts"],"sourcesContent":["import {\n  defaultTextFormatter,\n  type LogRecord,\n  type Sink,\n  type StreamSinkOptions,\n} from \"@logtape/logtape\";\n\n/**\n * Options for the {@link getBaseFileSink} function.\n */\nexport type FileSinkOptions = StreamSinkOptions & {\n  /**\n   * If `true`, the file is not opened until the first write.  Defaults to `false`.\n   */\n  lazy?: boolean;\n\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  /**\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\n/**\n * A platform-specific file sink driver.\n * @typeParam TFile The type of the file descriptor.\n */\nexport interface 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  /**\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  /**\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  /**\n   * Close the file.\n   * @param fd The file descriptor.\n   */\n  closeSync(fd: TFile): void;\n}\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.\n */\nexport function getBaseFileSink<TFile>(\n  path: string,\n  options: FileSinkOptions & FileSinkDriver<TFile>,\n): Sink & Disposable {\n  const formatter = options.formatter ?? defaultTextFormatter;\n  const encoder = options.encoder ?? new TextEncoder();\n  const bufferSize = options.bufferSize ?? 1024 * 8; // Default buffer size of 8192 chars\n  const flushInterval = options.flushInterval ?? 5000; // Default flush interval of 5 seconds\n  let fd = options.lazy ? null : options.openSync(path);\n  let buffer: string = \"\";\n  let lastFlushTimestamp: number = Date.now();\n\n  function flushBuffer(): void {\n    if (fd == null) return;\n    if (buffer.length > 0) {\n      options.writeSync(fd, encoder.encode(buffer));\n      buffer = \"\";\n      options.flushSync(fd);\n      lastFlushTimestamp = Date.now();\n    }\n  }\n\n  const sink: Sink & Disposable = (record: LogRecord) => {\n    if (fd == null) fd = options.openSync(path);\n    buffer += formatter(record);\n\n    const shouldFlushBySize = buffer.length >= bufferSize;\n    const shouldFlushByTime = flushInterval > 0 &&\n      (record.timestamp - lastFlushTimestamp) >= flushInterval;\n\n    if (shouldFlushBySize || shouldFlushByTime) {\n      flushBuffer();\n    }\n  };\n  sink[Symbol.dispose] = () => {\n    if (fd !== null) {\n      flushBuffer();\n      options.closeSync(fd);\n    }\n  };\n  return sink;\n}\n\n/**\n * Options for the {@link getBaseRotatingFileSink} function.\n */\nexport interface 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  /**\n   * The maximum number of files to keep.  5 by default.\n   */\n  maxFiles?: number;\n}\n\n/**\n * A platform-specific rotating file sink driver.\n */\nexport interface 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): { 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/**\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.\n */\nexport function getBaseRotatingFileSink<TFile>(\n  path: string,\n  options: RotatingFileSinkOptions & RotatingFileSinkDriver<TFile>,\n): Sink & Disposable {\n  const formatter = options.formatter ?? defaultTextFormatter;\n  const encoder = options.encoder ?? new TextEncoder();\n  const maxSize = options.maxSize ?? 1024 * 1024;\n  const maxFiles = options.maxFiles ?? 5;\n  const bufferSize = options.bufferSize ?? 1024 * 8; // Default buffer size of 8192 chars\n  const flushInterval = options.flushInterval ?? 5000; // Default flush interval of 5 seconds\n  let offset: number = 0;\n  try {\n    const stat = options.statSync(path);\n    offset = stat.size;\n  } catch {\n    // Continue as the offset is already 0.\n  }\n  let fd = options.openSync(path);\n  let lastFlushTimestamp: number = Date.now();\n\n  function shouldRollover(bytes: Uint8Array): boolean {\n    return offset + bytes.length > maxSize;\n  }\n  function performRollover(): void {\n    options.closeSync(fd);\n    for (let i = maxFiles - 1; i > 0; i--) {\n      const oldPath = `${path}.${i}`;\n      const newPath = `${path}.${i + 1}`;\n      try {\n        options.renameSync(oldPath, newPath);\n      } catch (_) {\n        // Continue if the file does not exist.\n      }\n    }\n    options.renameSync(path, `${path}.1`);\n    offset = 0;\n    fd = options.openSync(path);\n  }\n\n  function flushBuffer(): void {\n    if (buffer.length > 0) {\n      const bytes = encoder.encode(buffer);\n      buffer = \"\";\n      if (shouldRollover(bytes)) performRollover();\n      options.writeSync(fd, bytes);\n      options.flushSync(fd);\n      offset += bytes.length;\n      lastFlushTimestamp = Date.now();\n    }\n  }\n\n  let buffer: string = \"\";\n  const sink: Sink & Disposable = (record: LogRecord) => {\n    buffer += formatter(record);\n\n    const shouldFlushBySize = buffer.length >= bufferSize;\n    const shouldFlushByTime = flushInterval > 0 &&\n      (record.timestamp - lastFlushTimestamp) >= flushInterval;\n\n    if (shouldFlushBySize || shouldFlushByTime) {\n      flushBuffer();\n    }\n  };\n  sink[Symbol.dispose] = () => {\n    flushBuffer();\n    options.closeSync(fd);\n  };\n  return sink;\n}\n"],"mappings":";;;;;;;;;;;;AA2EA,SAAgB,gBACdA,MACAC,SACmB;CACnB,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,UAAU,QAAQ,WAAW,IAAI;CACvC,MAAM,aAAa,QAAQ,cAAc,OAAO;CAChD,MAAM,gBAAgB,QAAQ,iBAAiB;CAC/C,IAAI,KAAK,QAAQ,OAAO,OAAO,QAAQ,SAAS,KAAK;CACrD,IAAIC,SAAiB;CACrB,IAAIC,qBAA6B,KAAK,KAAK;CAE3C,SAAS,cAAoB;AAC3B,MAAI,MAAM,KAAM;AAChB,MAAI,OAAO,SAAS,GAAG;AACrB,WAAQ,UAAU,IAAI,QAAQ,OAAO,OAAO,CAAC;AAC7C,YAAS;AACT,WAAQ,UAAU,GAAG;AACrB,wBAAqB,KAAK,KAAK;EAChC;CACF;CAED,MAAMC,OAA0B,CAACC,WAAsB;AACrD,MAAI,MAAM,KAAM,MAAK,QAAQ,SAAS,KAAK;AAC3C,YAAU,UAAU,OAAO;EAE3B,MAAM,oBAAoB,OAAO,UAAU;EAC3C,MAAM,oBAAoB,gBAAgB,KACvC,OAAO,YAAY,sBAAuB;AAE7C,MAAI,qBAAqB,kBACvB,cAAa;CAEhB;AACD,MAAK,OAAO,WAAW,MAAM;AAC3B,MAAI,OAAO,MAAM;AACf,gBAAa;AACb,WAAQ,UAAU,GAAG;EACtB;CACF;AACD,QAAO;AACR;;;;;;;;;;;;;;AAiDD,SAAgB,wBACdL,MACAM,SACmB;CACnB,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,UAAU,QAAQ,WAAW,IAAI;CACvC,MAAM,UAAU,QAAQ,WAAW,OAAO;CAC1C,MAAM,WAAW,QAAQ,YAAY;CACrC,MAAM,aAAa,QAAQ,cAAc,OAAO;CAChD,MAAM,gBAAgB,QAAQ,iBAAiB;CAC/C,IAAIC,SAAiB;AACrB,KAAI;EACF,MAAM,OAAO,QAAQ,SAAS,KAAK;AACnC,WAAS,KAAK;CACf,QAAO,CAEP;CACD,IAAI,KAAK,QAAQ,SAAS,KAAK;CAC/B,IAAIJ,qBAA6B,KAAK,KAAK;CAE3C,SAAS,eAAeK,OAA4B;AAClD,SAAO,SAAS,MAAM,SAAS;CAChC;CACD,SAAS,kBAAwB;AAC/B,UAAQ,UAAU,GAAG;AACrB,OAAK,IAAI,IAAI,WAAW,GAAG,IAAI,GAAG,KAAK;GACrC,MAAM,WAAW,EAAE,KAAK,GAAG,EAAE;GAC7B,MAAM,WAAW,EAAE,KAAK,GAAG,IAAI,EAAE;AACjC,OAAI;AACF,YAAQ,WAAW,SAAS,QAAQ;GACrC,SAAQ,GAAG,CAEX;EACF;AACD,UAAQ,WAAW,OAAO,EAAE,KAAK,IAAI;AACrC,WAAS;AACT,OAAK,QAAQ,SAAS,KAAK;CAC5B;CAED,SAAS,cAAoB;AAC3B,MAAI,OAAO,SAAS,GAAG;GACrB,MAAM,QAAQ,QAAQ,OAAO,OAAO;AACpC,YAAS;AACT,OAAI,eAAe,MAAM,CAAE,kBAAiB;AAC5C,WAAQ,UAAU,IAAI,MAAM;AAC5B,WAAQ,UAAU,GAAG;AACrB,aAAU,MAAM;AAChB,wBAAqB,KAAK,KAAK;EAChC;CACF;CAED,IAAIN,SAAiB;CACrB,MAAME,OAA0B,CAACC,WAAsB;AACrD,YAAU,UAAU,OAAO;EAE3B,MAAM,oBAAoB,OAAO,UAAU;EAC3C,MAAM,oBAAoB,gBAAgB,KACvC,OAAO,YAAY,sBAAuB;AAE7C,MAAI,qBAAqB,kBACvB,cAAa;CAEhB;AACD,MAAK,OAAO,WAAW,MAAM;AAC3B,eAAa;AACb,UAAQ,UAAU,GAAG;CACtB;AACD,QAAO;AACR"}

package/filesink.base.ts

@@ -22,6 +22,15 @@ export type FileSinkOptions = StreamSinkOptions & {
    * @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;
 };
 
 /**
@@ -71,21 +80,36 @@ export function getBaseFileSink<TFile>(
   const formatter = options.formatter ?? defaultTextFormatter;
   const encoder = options.encoder ?? new TextEncoder();
   const bufferSize = options.bufferSize ?? 1024 * 8; // Default buffer size of 8192 chars
+  const flushInterval = options.flushInterval ?? 5000; // Default flush interval of 5 seconds
   let fd = options.lazy ? null : options.openSync(path);
   let buffer: string = "";
-  const sink: Sink & Disposable = (record: LogRecord) => {
-    if (fd == null) fd = options.openSync(path);
-    buffer += formatter(record);
-    if (buffer.length >= bufferSize) {
+  let lastFlushTimestamp: number = Date.now();
+
+  function flushBuffer(): void {
+    if (fd == null) return;
+    if (buffer.length > 0) {
       options.writeSync(fd, encoder.encode(buffer));
       buffer = "";
       options.flushSync(fd);
+      lastFlushTimestamp = Date.now();
+    }
+  }
+
+  const sink: Sink & Disposable = (record: LogRecord) => {
+    if (fd == null) fd = options.openSync(path);
+    buffer += formatter(record);
+
+    const shouldFlushBySize = buffer.length >= bufferSize;
+    const shouldFlushByTime = flushInterval > 0 &&
+      (record.timestamp - lastFlushTimestamp) >= flushInterval;
+
+    if (shouldFlushBySize || shouldFlushByTime) {
+      flushBuffer();
     }
   };
   sink[Symbol.dispose] = () => {
     if (fd !== null) {
-      options.writeSync(fd, encoder.encode(buffer));
-      options.flushSync(fd);
+      flushBuffer();
       options.closeSync(fd);
     }
   };
@@ -148,6 +172,7 @@ export function getBaseRotatingFileSink<TFile>(
   const maxSize = options.maxSize ?? 1024 * 1024;
   const maxFiles = options.maxFiles ?? 5;
   const bufferSize = options.bufferSize ?? 1024 * 8; // Default buffer size of 8192 chars
+  const flushInterval = options.flushInterval ?? 5000; // Default flush interval of 5 seconds
   let offset: number = 0;
   try {
     const stat = options.statSync(path);
@@ -156,6 +181,8 @@ export function getBaseRotatingFileSink<TFile>(
     // Continue as the offset is already 0.
   }
   let fd = options.openSync(path);
+  let lastFlushTimestamp: number = Date.now();
+
   function shouldRollover(bytes: Uint8Array): boolean {
     return offset + bytes.length > maxSize;
   }
@@ -174,21 +201,33 @@ export function getBaseRotatingFileSink<TFile>(
     offset = 0;
     fd = options.openSync(path);
   }
-  let buffer: string = "";
-  const sink: Sink & Disposable = (record: LogRecord) => {
-    buffer += formatter(record);
-    if (buffer.length >= bufferSize) {
+
+  function flushBuffer(): void {
+    if (buffer.length > 0) {
       const bytes = encoder.encode(buffer);
       buffer = "";
       if (shouldRollover(bytes)) performRollover();
       options.writeSync(fd, bytes);
       options.flushSync(fd);
       offset += bytes.length;
+      lastFlushTimestamp = Date.now();
+    }
+  }
+
+  let buffer: string = "";
+  const sink: Sink & Disposable = (record: LogRecord) => {
+    buffer += formatter(record);
+
+    const shouldFlushBySize = buffer.length >= bufferSize;
+    const shouldFlushByTime = flushInterval > 0 &&
+      (record.timestamp - lastFlushTimestamp) >= flushInterval;
+
+    if (shouldFlushBySize || shouldFlushByTime) {
+      flushBuffer();
     }
   };
   sink[Symbol.dispose] = () => {
-    options.writeSync(fd, encoder.encode(buffer));
-    options.flushSync(fd);
+    flushBuffer();
     options.closeSync(fd);
   };
   return sink;

package/filesink.test.ts

@@ -550,4 +550,145 @@ test("getBaseFileSink() with buffer edge cases", () => {
   );
 });
 
+test("getBaseFileSink() with time-based flushing", async () => {
+  const path = makeTempFileSync();
+  let sink: Sink & Disposable;
+  if (isDeno) {
+    const driver: FileSinkDriver<Deno.FsFile> = {
+      openSync(path: string) {
+        return Deno.openSync(path, { create: true, append: true });
+      },
+      writeSync(fd, chunk) {
+        fd.writeSync(chunk);
+      },
+      flushSync(fd) {
+        fd.syncSync();
+      },
+      closeSync(fd) {
+        fd.close();
+      },
+    };
+    sink = getBaseFileSink(path, {
+      ...driver,
+      bufferSize: 1000, // Large buffer to prevent size-based flushing
+      flushInterval: 100, // 100ms flush interval for testing
+    });
+  } else {
+    const driver: FileSinkDriver<number> = {
+      openSync(path: string) {
+        return fs.openSync(path, "a");
+      },
+      writeSync: fs.writeSync,
+      flushSync: fs.fsyncSync,
+      closeSync: fs.closeSync,
+    };
+    sink = getBaseFileSink(path, {
+      ...driver,
+      bufferSize: 1000, // Large buffer to prevent size-based flushing
+      flushInterval: 100, // 100ms flush interval for testing
+    });
+  }
+
+  // Create a log record with current timestamp
+  const record1 = { ...debug, timestamp: Date.now() };
+  sink(record1);
+
+  // Should be buffered (file empty initially)
+  assertEquals(fs.readFileSync(path, { encoding: "utf-8" }), "");
+
+  // Wait for flush interval to pass and write another record
+  await new Promise((resolve) => setTimeout(resolve, 150));
+  const record2 = { ...info, timestamp: Date.now() };
+  sink(record2);
+
+  // First record should now be flushed due to time interval
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assertEquals(content.includes("Hello, 123 & 456!"), true);
+
+  sink[Symbol.dispose]();
+});
+
+test("getRotatingFileSink() with time-based flushing", async () => {
+  const path = makeTempFileSync();
+  const sink: Sink & Disposable = getRotatingFileSink(path, {
+    maxSize: 1024 * 1024, // Large maxSize to prevent rotation
+    bufferSize: 1000, // Large buffer to prevent size-based flushing
+    flushInterval: 100, // 100ms flush interval for testing
+  });
+
+  // Create a log record with current timestamp
+  const record1 = { ...debug, timestamp: Date.now() };
+  sink(record1);
+
+  // Should be buffered (file empty initially)
+  assertEquals(fs.readFileSync(path, { encoding: "utf-8" }), "");
+
+  // Wait for flush interval to pass and write another record
+  await new Promise((resolve) => setTimeout(resolve, 150));
+  const record2 = { ...info, timestamp: Date.now() };
+  sink(record2);
+
+  // First record should now be flushed due to time interval
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assertEquals(content.includes("Hello, 123 & 456!"), true);
+
+  sink[Symbol.dispose]();
+});
+
+test("getBaseFileSink() with flushInterval disabled", () => {
+  const path = makeTempFileSync();
+  let sink: Sink & Disposable;
+  if (isDeno) {
+    const driver: FileSinkDriver<Deno.FsFile> = {
+      openSync(path: string) {
+        return Deno.openSync(path, { create: true, append: true });
+      },
+      writeSync(fd, chunk) {
+        fd.writeSync(chunk);
+      },
+      flushSync(fd) {
+        fd.syncSync();
+      },
+      closeSync(fd) {
+        fd.close();
+      },
+    };
+    sink = getBaseFileSink(path, {
+      ...driver,
+      bufferSize: 1000, // Large buffer to prevent size-based flushing
+      flushInterval: 0, // Disable time-based flushing
+    });
+  } else {
+    const driver: FileSinkDriver<number> = {
+      openSync(path: string) {
+        return fs.openSync(path, "a");
+      },
+      writeSync: fs.writeSync,
+      flushSync: fs.fsyncSync,
+      closeSync: fs.closeSync,
+    };
+    sink = getBaseFileSink(path, {
+      ...driver,
+      bufferSize: 1000, // Large buffer to prevent size-based flushing
+      flushInterval: 0, // Disable time-based flushing
+    });
+  }
+
+  // Create log records with simulated time gap
+  const now = Date.now();
+  const record1 = { ...debug, timestamp: now };
+  const record2 = { ...info, timestamp: now + 10000 }; // 10 seconds later
+
+  sink(record1);
+  sink(record2);
+
+  // Should still be buffered since time-based flushing is disabled
+  assertEquals(fs.readFileSync(path, { encoding: "utf-8" }), "");
+
+  // Only disposal should flush
+  sink[Symbol.dispose]();
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assertEquals(content.includes("Hello, 123 & 456!"), true);
+});
+
 // cSpell: ignore filesink

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/file",
-  "version": "0.12.0-dev.194+4b7c1127",
+  "version": "0.12.0-dev.196+8684bab0",
   "description": "File sink and rotating file sink for LogTape",
   "keywords": [
     "logging",
@@ -50,7 +50,7 @@
     }
   },
   "peerDependencies": {
-    "@logtape/logtape": "0.12.0-dev.194+4b7c1127"
+    "@logtape/logtape": "0.12.0-dev.196+8684bab0"
   },
   "devDependencies": {
     "@david/which-runtime": "npm:@jsr/david__which-runtime@^0.2.1",