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

package/filesink.base.ts

@@ -31,6 +31,16 @@ export type FileSinkOptions = StreamSinkOptions & {
    * @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;
 };
 
 /**
@@ -64,6 +74,25 @@ export interface FileSinkDriver<TFile> {
   closeSync(fd: TFile): void;
 }
 
+/**
+ * A platform-specific async file sink driver.
+ * @typeParam TFile The type of the file descriptor.
+ * @since 1.0.0
+ */
+export interface AsyncFileSinkDriver<TFile> extends FileSinkDriver<TFile> {
+  /**
+   * Asynchronously flush the file to ensure that all data is written to the disk.
+   * @param fd The file descriptor.
+   */
+  flush(fd: TFile): Promise<void>;
+
+  /**
+   * Asynchronously close the file.
+   * @param fd The file descriptor.
+   */
+  close(fd: TFile): Promise<void>;
+}
+
 /**
  * Get a platform-independent file sink.
  *
@@ -71,12 +100,23 @@ export interface FileSinkDriver<TFile> {
  * @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.
+ *          object that closes the file when disposed. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
  */
 export function getBaseFileSink<TFile>(
   path: string,
   options: FileSinkOptions & FileSinkDriver<TFile>,
-): Sink & Disposable {
+): Sink & Disposable;
+export function getBaseFileSink<TFile>(
+  path: string,
+  options: FileSinkOptions & AsyncFileSinkDriver<TFile>,
+): Sink & AsyncDisposable;
+export function getBaseFileSink<TFile>(
+  path: string,
+  options:
+    & FileSinkOptions
+    & (FileSinkDriver<TFile> | AsyncFileSinkDriver<TFile>),
+): Sink & (Disposable | AsyncDisposable) {
   const formatter = options.formatter ?? defaultTextFormatter;
   const encoder = options.encoder ?? new TextEncoder();
   const bufferSize = options.bufferSize ?? 1024 * 8; // Default buffer size of 8192 chars
@@ -85,18 +125,79 @@ export function getBaseFileSink<TFile>(
   let buffer: string = "";
   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);
+  if (!options.nonBlocking) {
+    // Blocking mode implementation
+    // deno-lint-ignore no-inner-declarations
+    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) {
+        flushBuffer();
+        options.closeSync(fd);
+      }
+    };
+    return sink;
+  }
+
+  // Non-blocking mode implementation
+  const asyncOptions = options as AsyncFileSinkDriver<TFile>;
+  let disposed = false;
+  let activeFlush: Promise<void> | null = null;
+  let flushTimer: ReturnType<typeof setInterval> | null = null;
+
+  async function flushBuffer(): Promise<void> {
+    if (fd == null || buffer.length === 0) return;
+
+    const data = buffer;
+    buffer = "";
+    try {
+      asyncOptions.writeSync(fd, encoder.encode(data));
+      await asyncOptions.flush(fd);
       lastFlushTimestamp = Date.now();
+    } catch {
+      // Silently ignore errors in non-blocking mode
     }
   }
 
-  const sink: Sink & Disposable = (record: LogRecord) => {
-    if (fd == null) fd = options.openSync(path);
+  function scheduleFlush(): void {
+    if (activeFlush || disposed) return;
+
+    activeFlush = flushBuffer().finally(() => {
+      activeFlush = null;
+    });
+  }
+
+  function startFlushTimer(): void {
+    if (flushTimer !== null || disposed) return;
+
+    flushTimer = setInterval(() => {
+      scheduleFlush();
+    }, flushInterval);
+  }
+
+  const nonBlockingSink: Sink & AsyncDisposable = (record: LogRecord) => {
+    if (disposed) return;
+    if (fd == null) fd = asyncOptions.openSync(path);
     buffer += formatter(record);
 
     const shouldFlushBySize = buffer.length >= bufferSize;
@@ -104,16 +205,29 @@ export function getBaseFileSink<TFile>(
       (record.timestamp - lastFlushTimestamp) >= flushInterval;
 
     if (shouldFlushBySize || shouldFlushByTime) {
-      flushBuffer();
+      scheduleFlush();
+    } else if (flushTimer === null && flushInterval > 0) {
+      startFlushTimer();
     }
   };
-  sink[Symbol.dispose] = () => {
+
+  nonBlockingSink[Symbol.asyncDispose] = async () => {
+    disposed = true;
+    if (flushTimer !== null) {
+      clearInterval(flushTimer);
+      flushTimer = null;
+    }
+    await flushBuffer();
     if (fd !== null) {
-      flushBuffer();
-      options.closeSync(fd);
+      try {
+        await asyncOptions.close(fd);
+      } catch {
+        // Writer might already be closed or errored
+      }
     }
   };
-  return sink;
+
+  return nonBlockingSink;
 }
 
 /**
@@ -150,6 +264,27 @@ export interface RotatingFileSinkDriver<TFile> extends FileSinkDriver<TFile> {
   renameSync(oldPath: string, newPath: string): void;
 }
 
+/**
+ * A platform-specific async rotating file sink driver.
+ * @since 1.0.0
+ */
+export interface AsyncRotatingFileSinkDriver<TFile>
+  extends AsyncFileSinkDriver<TFile> {
+  /**
+   * Get the size of the file.
+   * @param path A path to the file.
+   * @returns The `size` of the file in bytes, in an object.
+   */
+  statSync(path: string): { size: number };
+
+  /**
+   * Rename a file.
+   * @param oldPath A path to the file to rename.
+   * @param newPath A path to be renamed to.
+   */
+  renameSync(oldPath: string, newPath: string): void;
+}
+
 /**
  * Get a platform-independent rotating file sink.
  *
@@ -161,12 +296,23 @@ export interface RotatingFileSinkDriver<TFile> extends FileSinkDriver<TFile> {
  * @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.
+ *          object that closes the file when disposed. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
  */
 export function getBaseRotatingFileSink<TFile>(
   path: string,
   options: RotatingFileSinkOptions & RotatingFileSinkDriver<TFile>,
-): Sink & Disposable {
+): Sink & Disposable;
+export function getBaseRotatingFileSink<TFile>(
+  path: string,
+  options: RotatingFileSinkOptions & AsyncRotatingFileSinkDriver<TFile>,
+): Sink & AsyncDisposable;
+export function getBaseRotatingFileSink<TFile>(
+  path: string,
+  options:
+    & RotatingFileSinkOptions
+    & (RotatingFileSinkDriver<TFile> | AsyncRotatingFileSinkDriver<TFile>),
+): Sink & (Disposable | AsyncDisposable) {
   const formatter = options.formatter ?? defaultTextFormatter;
   const encoder = options.encoder ?? new TextEncoder();
   const maxSize = options.maxSize ?? 1024 * 1024;
@@ -182,6 +328,7 @@ export function getBaseRotatingFileSink<TFile>(
   }
   let fd = options.openSync(path);
   let lastFlushTimestamp: number = Date.now();
+  let buffer: string = "";
 
   function shouldRollover(bytes: Uint8Array): boolean {
     return offset + bytes.length > maxSize;
@@ -202,20 +349,80 @@ export function getBaseRotatingFileSink<TFile>(
     fd = options.openSync(path);
   }
 
-  function flushBuffer(): void {
-    if (buffer.length > 0) {
-      const bytes = encoder.encode(buffer);
-      buffer = "";
+  if (!options.nonBlocking) {
+    // Blocking mode implementation
+    // deno-lint-ignore no-inner-declarations
+    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();
+      }
+    }
+
+    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] = () => {
+      flushBuffer();
+      options.closeSync(fd);
+    };
+    return sink;
+  }
+
+  // Non-blocking mode implementation
+  const asyncOptions = options as AsyncRotatingFileSinkDriver<TFile>;
+  let disposed = false;
+  let activeFlush: Promise<void> | null = null;
+  let flushTimer: ReturnType<typeof setInterval> | null = null;
+
+  async function flushBuffer(): Promise<void> {
+    if (buffer.length === 0) return;
+
+    const data = buffer;
+    buffer = "";
+    try {
+      const bytes = encoder.encode(data);
       if (shouldRollover(bytes)) performRollover();
-      options.writeSync(fd, bytes);
-      options.flushSync(fd);
+      asyncOptions.writeSync(fd, bytes);
+      await asyncOptions.flush(fd);
       offset += bytes.length;
       lastFlushTimestamp = Date.now();
+    } catch {
+      // Silently ignore errors in non-blocking mode
     }
   }
 
-  let buffer: string = "";
-  const sink: Sink & Disposable = (record: LogRecord) => {
+  function scheduleFlush(): void {
+    if (activeFlush || disposed) return;
+
+    activeFlush = flushBuffer().finally(() => {
+      activeFlush = null;
+    });
+  }
+
+  function startFlushTimer(): void {
+    if (flushTimer !== null || disposed) return;
+
+    flushTimer = setInterval(() => {
+      scheduleFlush();
+    }, flushInterval);
+  }
+
+  const nonBlockingSink: Sink & AsyncDisposable = (record: LogRecord) => {
+    if (disposed) return;
     buffer += formatter(record);
 
     const shouldFlushBySize = buffer.length >= bufferSize;
@@ -223,12 +430,25 @@ export function getBaseRotatingFileSink<TFile>(
       (record.timestamp - lastFlushTimestamp) >= flushInterval;
 
     if (shouldFlushBySize || shouldFlushByTime) {
-      flushBuffer();
+      scheduleFlush();
+    } else if (flushTimer === null && flushInterval > 0) {
+      startFlushTimer();
     }
   };
-  sink[Symbol.dispose] = () => {
-    flushBuffer();
-    options.closeSync(fd);
+
+  nonBlockingSink[Symbol.asyncDispose] = async () => {
+    disposed = true;
+    if (flushTimer !== null) {
+      clearInterval(flushTimer);
+      flushTimer = null;
+    }
+    await flushBuffer();
+    try {
+      await asyncOptions.close(fd);
+    } catch {
+      // Writer might already be closed or errored
+    }
   };
-  return sink;
+
+  return nonBlockingSink;
 }

package/filesink.deno.ts

@@ -1,5 +1,6 @@
 import type { Sink } from "@logtape/logtape";
 import {
+  type AsyncRotatingFileSinkDriver,
   type FileSinkOptions,
   getBaseFileSink,
   getBaseRotatingFileSink,
@@ -27,6 +28,20 @@ export const denoDriver: RotatingFileSinkDriver<Deno.FsFile> = {
   renameSync: globalThis?.Deno.renameSync,
 };
 
+/**
+ * A Deno-specific async file sink driver.
+ * @since 1.0.0
+ */
+export const denoAsyncDriver: AsyncRotatingFileSinkDriver<Deno.FsFile> = {
+  ...denoDriver,
+  async flush(fd) {
+    await fd.sync();
+  },
+  close(fd) {
+    return Promise.resolve(fd.close());
+  },
+};
+
 /**
  * Get a file sink.
  *
@@ -35,12 +50,24 @@ export const denoDriver: RotatingFileSinkDriver<Deno.FsFile> = {
  * @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.
+ *          object that closes the file when disposed. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
  */
+export function getFileSink(
+  path: string,
+  options?: FileSinkOptions,
+): Sink & Disposable;
+export function getFileSink(
+  path: string,
+  options: FileSinkOptions & { nonBlocking: true },
+): Sink & AsyncDisposable;
 export function getFileSink(
   path: string,
   options: FileSinkOptions = {},
-): Sink & Disposable {
+): Sink & (Disposable | AsyncDisposable) {
+  if (options.nonBlocking) {
+    return getBaseFileSink(path, { ...options, ...denoAsyncDriver });
+  }
   return getBaseFileSink(path, { ...options, ...denoDriver });
 }
 
@@ -57,12 +84,24 @@ export function getFileSink(
  * @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.
+ *          object that closes the file when disposed. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
  */
+export function getRotatingFileSink(
+  path: string,
+  options?: RotatingFileSinkOptions,
+): Sink & Disposable;
+export function getRotatingFileSink(
+  path: string,
+  options: RotatingFileSinkOptions & { nonBlocking: true },
+): Sink & AsyncDisposable;
 export function getRotatingFileSink(
   path: string,
   options: RotatingFileSinkOptions = {},
-): Sink & Disposable {
+): Sink & (Disposable | AsyncDisposable) {
+  if (options.nonBlocking) {
+    return getBaseRotatingFileSink(path, { ...options, ...denoAsyncDriver });
+  }
   return getBaseRotatingFileSink(path, { ...options, ...denoDriver });
 }
 

package/filesink.jsr.ts

@@ -4,7 +4,10 @@ import type {
   RotatingFileSinkOptions,
 } from "./filesink.base.ts";
 
-const filesink: Omit<typeof import("./filesink.deno.ts"), "denoDriver"> =
+const filesink: Omit<
+  typeof import("./filesink.deno.ts"),
+  "denoDriver" | "denoAsyncDriver"
+> =
   // dnt-shim-ignore
   await ("Deno" in globalThis
     ? import("./filesink.deno.ts")
@@ -18,13 +21,24 @@ const filesink: Omit<typeof import("./filesink.deno.ts"), "denoDriver"> =
  * @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.
+ *          object that closes the file when disposed. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
  */
+export function getFileSink(
+  path: string,
+  options?: FileSinkOptions,
+): Sink & Disposable;
+export function getFileSink(
+  path: string,
+  options: FileSinkOptions & { nonBlocking: true },
+): Sink & AsyncDisposable;
 export function getFileSink(
   path: string,
   options: FileSinkOptions = {},
-): Sink & Disposable {
-  return filesink.getFileSink(path, options);
+): Sink & (Disposable | AsyncDisposable) {
+  return filesink.getFileSink(path, options) as
+    & Sink
+    & (Disposable | AsyncDisposable);
 }
 
 /**
@@ -40,13 +54,24 @@ export function getFileSink(
  * @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.
+ *          object that closes the file when disposed. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
  */
+export function getRotatingFileSink(
+  path: string,
+  options?: RotatingFileSinkOptions,
+): Sink & Disposable;
+export function getRotatingFileSink(
+  path: string,
+  options: RotatingFileSinkOptions & { nonBlocking: true },
+): Sink & AsyncDisposable;
 export function getRotatingFileSink(
   path: string,
   options: RotatingFileSinkOptions = {},
-): Sink & Disposable {
-  return filesink.getRotatingFileSink(path, options);
+): Sink & (Disposable | AsyncDisposable) {
+  return filesink.getRotatingFileSink(path, options) as
+    & Sink
+    & (Disposable | AsyncDisposable);
 }
 
 // cSpell: ignore filesink

package/filesink.node.ts

@@ -1,6 +1,8 @@
 import type { Sink } from "@logtape/logtape";
 import fs from "node:fs";
+import { promisify } from "node:util";
 import {
+  type AsyncRotatingFileSinkDriver,
   type FileSinkOptions,
   getBaseFileSink,
   getBaseRotatingFileSink,
@@ -22,6 +24,16 @@ export const nodeDriver: RotatingFileSinkDriver<number | void> = {
   renameSync: fs.renameSync,
 };
 
+/**
+ * A Node.js-specific async file sink driver.
+ * @since 1.0.0
+ */
+export const nodeAsyncDriver: AsyncRotatingFileSinkDriver<number | void> = {
+  ...nodeDriver,
+  flush: promisify(fs.fsync),
+  close: promisify(fs.close),
+};
+
 /**
  * Get a file sink.
  *
@@ -30,12 +42,24 @@ export const nodeDriver: RotatingFileSinkDriver<number | void> = {
  * @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.
+ *          object that closes the file when disposed. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
  */
+export function getFileSink(
+  path: string,
+  options?: FileSinkOptions,
+): Sink & Disposable;
+export function getFileSink(
+  path: string,
+  options: FileSinkOptions & { nonBlocking: true },
+): Sink & AsyncDisposable;
 export function getFileSink(
   path: string,
   options: FileSinkOptions = {},
-): Sink & Disposable {
+): Sink & (Disposable | AsyncDisposable) {
+  if (options.nonBlocking) {
+    return getBaseFileSink(path, { ...options, ...nodeAsyncDriver });
+  }
   return getBaseFileSink(path, { ...options, ...nodeDriver });
 }
 
@@ -52,12 +76,24 @@ export function getFileSink(
  * @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.
+ *          object that closes the file when disposed. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
  */
+export function getRotatingFileSink(
+  path: string,
+  options?: RotatingFileSinkOptions,
+): Sink & Disposable;
+export function getRotatingFileSink(
+  path: string,
+  options: RotatingFileSinkOptions & { nonBlocking: true },
+): Sink & AsyncDisposable;
 export function getRotatingFileSink(
   path: string,
   options: RotatingFileSinkOptions = {},
-): Sink & Disposable {
+): Sink & (Disposable | AsyncDisposable) {
+  if (options.nonBlocking) {
+    return getBaseRotatingFileSink(path, { ...options, ...nodeAsyncDriver });
+  }
   return getBaseRotatingFileSink(path, { ...options, ...nodeDriver });
 }