@logtape/file 1.0.0-dev.246 → 1.0.0-dev.248

package/filesink.deno.ts

@@ -1,5 +1,6 @@
 import type { Sink } from "@logtape/logtape";
 import {
+  type AsyncRotatingFileSinkDriver,
   type FileSinkOptions,
   getBaseFileSink,
   getBaseRotatingFileSink,
@@ -17,6 +18,13 @@ export const denoDriver: RotatingFileSinkDriver<Deno.FsFile> = {
   writeSync(fd, chunk) {
     fd.writeSync(chunk);
   },
+  writeManySync(fd: Deno.FsFile, chunks: Uint8Array[]): void {
+    // Deno doesn't have writev, but we can optimize by writing all chunks
+    // then doing a single sync operation
+    for (const chunk of chunks) {
+      fd.writeSync(chunk);
+    }
+  },
   flushSync(fd) {
     fd.syncSync();
   },
@@ -27,6 +35,27 @@ 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 writeMany(fd: Deno.FsFile, chunks: Uint8Array[]): Promise<void> {
+    // Deno doesn't have async writev, but we can write all chunks
+    // then do a single async sync
+    for (const chunk of chunks) {
+      await fd.write(chunk);
+    }
+  },
+  async flush(fd) {
+    await fd.sync();
+  },
+  close(fd) {
+    return Promise.resolve(fd.close());
+  },
+};
+
 /**
  * Get a file sink.
  *
@@ -35,12 +64,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 +98,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,
@@ -16,12 +18,40 @@ export const nodeDriver: RotatingFileSinkDriver<number | void> = {
     return fs.openSync(path, "a");
   },
   writeSync: fs.writeSync,
+  writeManySync(fd: number, chunks: Uint8Array[]): void {
+    if (chunks.length === 0) return;
+    if (chunks.length === 1) {
+      fs.writeSync(fd, chunks[0]);
+      return;
+    }
+    // Use writev for multiple chunks
+    fs.writevSync(fd, chunks);
+  },
   flushSync: fs.fsyncSync,
   closeSync: fs.closeSync,
   statSync: fs.statSync,
   renameSync: fs.renameSync,
 };
 
+/**
+ * A Node.js-specific async file sink driver.
+ * @since 1.0.0
+ */
+export const nodeAsyncDriver: AsyncRotatingFileSinkDriver<number | void> = {
+  ...nodeDriver,
+  async writeMany(fd: number, chunks: Uint8Array[]): Promise<void> {
+    if (chunks.length === 0) return;
+    if (chunks.length === 1) {
+      await promisify(fs.write)(fd, chunks[0]);
+      return;
+    }
+    // Use async writev for multiple chunks
+    await promisify(fs.writev)(fd, chunks);
+  },
+  flush: promisify(fs.fsync),
+  close: promisify(fs.close),
+};
+
 /**
  * Get a file sink.
  *
@@ -30,12 +60,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 +94,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 });
 }
 

package/filesink.test.ts

@@ -2,8 +2,10 @@ import { getFileSink, getRotatingFileSink } from "#filesink";
 import { suite } from "@alinea/suite";
 import { isDeno } from "@david/which-runtime";
 import type { Sink } from "@logtape/logtape";
+import { assert } from "@std/assert/assert";
 import { assertEquals } from "@std/assert/equals";
 import { assertThrows } from "@std/assert/throws";
+import { delay } from "@std/async/delay";
 import { join } from "@std/path/join";
 import fs from "node:fs";
 import { tmpdir } from "node:os";
@@ -691,4 +693,122 @@ test("getBaseFileSink() with flushInterval disabled", () => {
   assertEquals(content.includes("Hello, 123 & 456!"), true);
 });
 
+test("getFileSink() with nonBlocking mode", async () => {
+  const path = makeTempFileSync();
+  const sink = getFileSink(path, {
+    nonBlocking: true,
+    bufferSize: 50, // Small buffer to trigger flush by size
+  });
+
+  // Check that it returns AsyncDisposable
+  assert(typeof sink === "function");
+  assert(Symbol.asyncDispose in sink);
+
+  // Add enough records to trigger buffer flush
+  sink(debug);
+  sink(info);
+
+  // Wait for async flush to complete
+  await delay(50);
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assert(content.includes("Hello, 123 & 456!"));
+
+  await (sink as Sink & AsyncDisposable)[Symbol.asyncDispose]();
+});
+
+test("getRotatingFileSink() with nonBlocking mode", async () => {
+  const path = makeTempFileSync();
+  const sink = getRotatingFileSink(path, {
+    maxSize: 200,
+    nonBlocking: true,
+    bufferSize: 1000, // Large buffer to prevent immediate flush
+    flushInterval: 50, // Short interval for testing
+  });
+
+  // Check that it returns AsyncDisposable
+  assert(typeof sink === "function");
+  assert(Symbol.asyncDispose in sink);
+
+  // Add records with current timestamp
+  const record1 = { ...debug, timestamp: Date.now() };
+  const record2 = { ...info, timestamp: Date.now() };
+  sink(record1);
+  sink(record2);
+  assertEquals(fs.readFileSync(path, { encoding: "utf-8" }), ""); // Not written yet
+
+  // Wait for flush interval to pass
+  await delay(100);
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assert(content.includes("Hello, 123 & 456!"));
+
+  await (sink as Sink & AsyncDisposable)[Symbol.asyncDispose]();
+});
+
+test("getFileSink() with nonBlocking high-volume logging", async () => {
+  const path = makeTempFileSync();
+  const sink = getFileSink(path, {
+    nonBlocking: true,
+    bufferSize: 50, // Small buffer to trigger flush
+    flushInterval: 0, // Disable time-based flushing for this test
+  }) as unknown as Sink & AsyncDisposable;
+
+  // Add enough records to trigger buffer flush (50 chars per record roughly)
+  let totalChars = 0;
+  let recordCount = 0;
+  while (totalChars < 100) { // Exceed buffer size
+    sink(debug);
+    totalChars += 67; // Approximate length of each debug record
+    recordCount++;
+  }
+
+  // Wait for async flush to complete
+  await delay(50);
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+
+  // Should have some records written by now
+  const writtenCount = (content.match(/Hello, 123 & 456!/g) || []).length;
+  assert(
+    writtenCount > 0,
+    `Expected some records to be written, but got ${writtenCount}`,
+  );
+
+  await sink[Symbol.asyncDispose]();
+});
+
+test("getRotatingFileSink() with nonBlocking rotation", async () => {
+  const path = makeTempFileSync();
+  const sink = getRotatingFileSink(path, {
+    maxSize: 150, // Small size to trigger rotation
+    nonBlocking: true,
+    bufferSize: 100,
+    flushInterval: 10,
+  }) as unknown as Sink & AsyncDisposable;
+
+  // Add enough records to trigger rotation
+  sink(debug);
+  sink(info);
+  sink(warning);
+  sink(error);
+
+  // Wait for all flushes and rotation to complete
+  await delay(200);
+
+  // Check that rotation occurred
+  const mainContent = fs.readFileSync(path, { encoding: "utf-8" });
+  let rotatedContent = "";
+  try {
+    rotatedContent = fs.readFileSync(`${path}.1`, { encoding: "utf-8" });
+  } catch {
+    // No rotation occurred
+  }
+
+  const allContent = mainContent + rotatedContent;
+
+  // Should have all 4 records somewhere
+  const recordCount = (allContent.match(/Hello, 123 & 456!/g) || []).length;
+  assertEquals(recordCount, 4);
+
+  await sink[Symbol.asyncDispose]();
+});
+
 // cSpell: ignore filesink

package/mod.ts

@@ -4,4 +4,6 @@ export type {
   RotatingFileSinkDriver,
   RotatingFileSinkOptions,
 } from "./filesink.base.ts";
+export type { StreamFileSinkOptions } from "./streamfilesink.ts";
 export { getFileSink, getRotatingFileSink } from "#filesink";
+export { getStreamFileSink } from "./streamfilesink.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/file",
-  "version": "1.0.0-dev.246+c7630de7",
+  "version": "1.0.0-dev.248+f96c618d",
   "description": "File sink and rotating file sink for LogTape",
   "keywords": [
     "logging",
@@ -55,13 +55,15 @@
       "require": "./dist/filesink.node.cjs"
     }
   },
+  "sideEffects": false,
   "peerDependencies": {
-    "@logtape/logtape": "1.0.0-dev.246+c7630de7"
+    "@logtape/logtape": "1.0.0-dev.248+f96c618d"
   },
   "devDependencies": {
     "@alinea/suite": "^0.6.3",
     "@david/which-runtime": "npm:@jsr/david__which-runtime@^0.2.1",
     "@std/assert": "npm:@jsr/std__assert@^1.0.13",
+    "@std/async": "npm:@jsr/std__async@^1.0.13",
     "@std/path": "npm:@jsr/std__path@^1.1.0",
     "tsdown": "^0.12.7",
     "typescript": "^5.8.3"