@logtape/logtape 1.0.0-dev.207 → 1.0.0-dev.208

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/logtape",
-  "version": "1.0.0-dev.207+2b6ea0e4",
+  "version": "1.0.0-dev.208+b3f9fea2",
   "license": "MIT",
   "exports": "./mod.ts",
   "imports": {

package/dist/mod.cjs

@@ -30,5 +30,6 @@ exports.parseLogLevel = require_level.parseLogLevel;
 exports.reset = require_config.reset;
 exports.resetSync = require_config.resetSync;
 exports.toFilter = require_filter.toFilter;
+exports.withBuffer = require_sink.withBuffer;
 exports.withContext = require_context.withContext;
 exports.withFilter = require_sink.withFilter;

package/dist/mod.d.cts

@@ -3,7 +3,7 @@ import { LogLevel, compareLogLevel, getLogLevels, isLogLevel, parseLogLevel } fr
 import { LogRecord } from "./record.cjs";
 import { Filter, FilterLike, getLevelFilter, toFilter } from "./filter.cjs";
 import { AnsiColor, AnsiColorFormatterOptions, AnsiStyle, ConsoleFormatter, FormattedValues, JsonLinesFormatterOptions, TextFormatter, TextFormatterOptions, ansiColorFormatter, defaultConsoleFormatter, defaultTextFormatter, getAnsiColorFormatter, getJsonLinesFormatter, getTextFormatter, jsonLinesFormatter } from "./formatter.cjs";
-import { ConsoleSinkOptions, Sink, StreamSinkOptions, getConsoleSink, getStreamSink, withFilter } from "./sink.cjs";
+import { BufferSinkOptions, ConsoleSinkOptions, Sink, StreamSinkOptions, getConsoleSink, getStreamSink, withBuffer, withFilter } from "./sink.cjs";
 import { Config, ConfigError, LoggerConfig, configure, configureSync, dispose, disposeSync, getConfig, reset, resetSync } from "./config.cjs";
 import { LogMethod, Logger, getLogger } from "./logger.cjs";
-export { AnsiColor, AnsiColorFormatterOptions, AnsiStyle, Config, ConfigError, ConsoleFormatter, ConsoleSinkOptions, ContextLocalStorage, Filter, FilterLike, FormattedValues, JsonLinesFormatterOptions, LogLevel, LogMethod, LogRecord, Logger, LoggerConfig, Sink, StreamSinkOptions, TextFormatter, TextFormatterOptions, ansiColorFormatter, compareLogLevel, configure, configureSync, defaultConsoleFormatter, defaultTextFormatter, dispose, disposeSync, getAnsiColorFormatter, getConfig, getConsoleSink, getJsonLinesFormatter, getLevelFilter, getLogLevels, getLogger, getStreamSink, getTextFormatter, isLogLevel, jsonLinesFormatter, parseLogLevel, reset, resetSync, toFilter, withContext, withFilter };
+export { AnsiColor, AnsiColorFormatterOptions, AnsiStyle, BufferSinkOptions, Config, ConfigError, ConsoleFormatter, ConsoleSinkOptions, ContextLocalStorage, Filter, FilterLike, FormattedValues, JsonLinesFormatterOptions, LogLevel, LogMethod, LogRecord, Logger, LoggerConfig, Sink, StreamSinkOptions, TextFormatter, TextFormatterOptions, ansiColorFormatter, compareLogLevel, configure, configureSync, defaultConsoleFormatter, defaultTextFormatter, dispose, disposeSync, getAnsiColorFormatter, getConfig, getConsoleSink, getJsonLinesFormatter, getLevelFilter, getLogLevels, getLogger, getStreamSink, getTextFormatter, isLogLevel, jsonLinesFormatter, parseLogLevel, reset, resetSync, toFilter, withBuffer, withContext, withFilter };

package/dist/mod.d.ts

@@ -3,7 +3,7 @@ import { LogLevel, compareLogLevel, getLogLevels, isLogLevel, parseLogLevel } fr
 import { LogRecord } from "./record.js";
 import { Filter, FilterLike, getLevelFilter, toFilter } from "./filter.js";
 import { AnsiColor, AnsiColorFormatterOptions, AnsiStyle, ConsoleFormatter, FormattedValues, JsonLinesFormatterOptions, TextFormatter, TextFormatterOptions, ansiColorFormatter, defaultConsoleFormatter, defaultTextFormatter, getAnsiColorFormatter, getJsonLinesFormatter, getTextFormatter, jsonLinesFormatter } from "./formatter.js";
-import { ConsoleSinkOptions, Sink, StreamSinkOptions, getConsoleSink, getStreamSink, withFilter } from "./sink.js";
+import { BufferSinkOptions, ConsoleSinkOptions, Sink, StreamSinkOptions, getConsoleSink, getStreamSink, withBuffer, withFilter } from "./sink.js";
 import { Config, ConfigError, LoggerConfig, configure, configureSync, dispose, disposeSync, getConfig, reset, resetSync } from "./config.js";
 import { LogMethod, Logger, getLogger } from "./logger.js";
-export { AnsiColor, AnsiColorFormatterOptions, AnsiStyle, Config, ConfigError, ConsoleFormatter, ConsoleSinkOptions, ContextLocalStorage, Filter, FilterLike, FormattedValues, JsonLinesFormatterOptions, LogLevel, LogMethod, LogRecord, Logger, LoggerConfig, Sink, StreamSinkOptions, TextFormatter, TextFormatterOptions, ansiColorFormatter, compareLogLevel, configure, configureSync, defaultConsoleFormatter, defaultTextFormatter, dispose, disposeSync, getAnsiColorFormatter, getConfig, getConsoleSink, getJsonLinesFormatter, getLevelFilter, getLogLevels, getLogger, getStreamSink, getTextFormatter, isLogLevel, jsonLinesFormatter, parseLogLevel, reset, resetSync, toFilter, withContext, withFilter };
+export { AnsiColor, AnsiColorFormatterOptions, AnsiStyle, BufferSinkOptions, Config, ConfigError, ConsoleFormatter, ConsoleSinkOptions, ContextLocalStorage, Filter, FilterLike, FormattedValues, JsonLinesFormatterOptions, LogLevel, LogMethod, LogRecord, Logger, LoggerConfig, Sink, StreamSinkOptions, TextFormatter, TextFormatterOptions, ansiColorFormatter, compareLogLevel, configure, configureSync, defaultConsoleFormatter, defaultTextFormatter, dispose, disposeSync, getAnsiColorFormatter, getConfig, getConsoleSink, getJsonLinesFormatter, getLevelFilter, getLogLevels, getLogger, getStreamSink, getTextFormatter, isLogLevel, jsonLinesFormatter, parseLogLevel, reset, resetSync, toFilter, withBuffer, withContext, withFilter };

package/dist/mod.js

@@ -2,8 +2,8 @@ import { getLevelFilter, toFilter } from "./filter.js";
 import { compareLogLevel, getLogLevels, isLogLevel, parseLogLevel } from "./level.js";
 import { getLogger } from "./logger.js";
 import { ansiColorFormatter, defaultConsoleFormatter, defaultTextFormatter, getAnsiColorFormatter, getJsonLinesFormatter, getTextFormatter, jsonLinesFormatter } from "./formatter.js";
-import { getConsoleSink, getStreamSink, withFilter } from "./sink.js";
+import { getConsoleSink, getStreamSink, withBuffer, withFilter } from "./sink.js";
 import { ConfigError, configure, configureSync, dispose, disposeSync, getConfig, reset, resetSync } from "./config.js";
 import { withContext } from "./context.js";
 
-export { ConfigError, ansiColorFormatter, compareLogLevel, configure, configureSync, defaultConsoleFormatter, defaultTextFormatter, dispose, disposeSync, getAnsiColorFormatter, getConfig, getConsoleSink, getJsonLinesFormatter, getLevelFilter, getLogLevels, getLogger, getStreamSink, getTextFormatter, isLogLevel, jsonLinesFormatter, parseLogLevel, reset, resetSync, toFilter, withContext, withFilter };
+export { ConfigError, ansiColorFormatter, compareLogLevel, configure, configureSync, defaultConsoleFormatter, defaultTextFormatter, dispose, disposeSync, getAnsiColorFormatter, getConfig, getConsoleSink, getJsonLinesFormatter, getLevelFilter, getLogLevels, getLogger, getStreamSink, getTextFormatter, isLogLevel, jsonLinesFormatter, parseLogLevel, reset, resetSync, toFilter, withBuffer, withContext, withFilter };

package/dist/sink.cjs

@@ -23,6 +23,68 @@ function withFilter(sink, filter) {
 	};
 }
 /**
+* Turns a sink into a buffered sink.  The returned sink buffers log records
+* in memory and flushes them to the underlying sink when the buffer is full
+* or after a specified time interval.
+*
+* @example Buffer a console sink with custom options
+* ```typescript
+* const sink = withBuffer(getConsoleSink(), {
+*   bufferSize: 5,
+*   flushInterval: 1000
+* });
+* ```
+*
+* @param sink A sink to be buffered.
+* @param options Options for the buffered sink.
+* @returns A buffered sink that flushes records periodically.
+* @since 1.0.0
+*/
+function withBuffer(sink, options = {}) {
+	const bufferSize = options.bufferSize ?? 10;
+	const flushInterval = options.flushInterval ?? 5e3;
+	const buffer = [];
+	let flushTimer = null;
+	let disposed = false;
+	function flush() {
+		if (buffer.length === 0) return;
+		const records = buffer.splice(0);
+		for (const record of records) try {
+			sink(record);
+		} catch (error) {
+			throw error;
+		}
+		if (flushTimer !== null) {
+			clearTimeout(flushTimer);
+			flushTimer = null;
+		}
+	}
+	function scheduleFlush() {
+		if (flushInterval <= 0 || flushTimer !== null || disposed) return;
+		flushTimer = setTimeout(() => {
+			flushTimer = null;
+			flush();
+		}, flushInterval);
+	}
+	const bufferedSink = (record) => {
+		if (disposed) return;
+		buffer.push(record);
+		if (buffer.length >= bufferSize) flush();
+		else scheduleFlush();
+	};
+	bufferedSink[Symbol.asyncDispose] = async () => {
+		disposed = true;
+		if (flushTimer !== null) {
+			clearTimeout(flushTimer);
+			flushTimer = null;
+		}
+		flush();
+		if (Symbol.asyncDispose in sink) await sink[Symbol.asyncDispose]();
+		else if (Symbol.dispose in sink) sink[Symbol.dispose]();
+	};
+	return bufferedSink;
+}
+/**
 * A factory that returns a sink that writes to a {@link WritableStream}.
 *
 * Note that the `stream` is of Web Streams API, which is different from
@@ -93,4 +155,5 @@ function getConsoleSink(options = {}) {
 //#endregion
 exports.getConsoleSink = getConsoleSink;
 exports.getStreamSink = getStreamSink;
+exports.withBuffer = withBuffer;
 exports.withFilter = withFilter;

package/dist/sink.d.cts

@@ -30,6 +30,44 @@ type Sink = (record: LogRecord) => void;
  * @returns A sink that only logs records that pass the filter.
  */
 declare function withFilter(sink: Sink, filter: FilterLike): Sink;
+/**
+ * Options for the {@link withBuffer} function.
+ * @since 1.0.0
+ */
+interface BufferSinkOptions {
+  /**
+   * The maximum number of log records to buffer before flushing to the
+   * underlying sink.
+   * @default `10`
+   */
+  bufferSize?: number;
+  /**
+   * The maximum time in milliseconds to wait before flushing buffered records
+   * to the underlying sink.  Defaults to 5000 (5 seconds).  Set to 0 or
+   * negative to disable time-based flushing.
+   * @default `5000`
+   */
+  flushInterval?: number;
+}
+/**
+ * Turns a sink into a buffered sink.  The returned sink buffers log records
+ * in memory and flushes them to the underlying sink when the buffer is full
+ * or after a specified time interval.
+ *
+ * @example Buffer a console sink with custom options
+ * ```typescript
+ * const sink = withBuffer(getConsoleSink(), {
+ *   bufferSize: 5,
+ *   flushInterval: 1000
+ * });
+ * ```
+ *
+ * @param sink A sink to be buffered.
+ * @param options Options for the buffered sink.
+ * @returns A buffered sink that flushes records periodically.
+ * @since 1.0.0
+ */
+declare function withBuffer(sink: Sink, options?: BufferSinkOptions): Sink & AsyncDisposable;
 /**
  * Options for the {@link getStreamSink} function.
  */
@@ -109,5 +147,5 @@ interface ConsoleSinkOptions {
  */
 declare function getConsoleSink(options?: ConsoleSinkOptions): Sink;
 //#endregion
-export { ConsoleSinkOptions, Sink, StreamSinkOptions, getConsoleSink, getStreamSink, withFilter };
+export { BufferSinkOptions, ConsoleSinkOptions, Sink, StreamSinkOptions, getConsoleSink, getStreamSink, withBuffer, withFilter };
 //# sourceMappingURL=sink.d.cts.map

package/dist/sink.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"sink.d.cts","names":[],"sources":["../sink.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAmBA;AAgBA;;;;;AAAgE;AAU/C,KA1BL,IAAA,GA0BK,CAAA,MAAiB,EA1BN,SA0BM,EAAA,GAAA,IAAA;;;;AASY;AA2B9C;;;;;;AAGyB;AAgBxB;AAOD;;AAKc,iBA7EE,UAAA,CA6EF,IAAA,EA7EmB,IA6EnB,EAAA,MAAA,EA7EiC,UA6EjC,CAAA,EA7E8C,IA6E9C;;;;AAiBD,UApFI,iBAAA,CAoFJ;EAAM;AAKA;AASnB;EAA8B,SAAA,CAAA,EA9FhB,aA8FgB;EAAA;;AAAwC;;0BAzFlC;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BpB,aAAA,SACN,0BACC,oBACR,OAAO;KAkBL,aAAA;;;;UAKY,kBAAA;;;;;cAKH,mBAAmB;;;;;;;;;;;;;;;;aAiBpB,OAAO,UAAU;;;;YAKlB;;;;;;;;iBASI,cAAA,WAAwB,qBAA0B"}
+{"version":3,"file":"sink.d.cts","names":[],"sources":["../sink.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAmBA;AAgBA;;;;;AAAgE;AAW/C,KA3BL,IAAA,GA2BK,CAAA,MAAiB,EA3BN,SA2BM,EAAA,GAAA,IAAA;AAmClC;;;;;;AAGyB;AAsEzB;;;;AAS8C;AA2B9C;;AACU,iBA5JM,UAAA,CA4JN,IAAA,EA5JuB,IA4JvB,EAAA,MAAA,EA5JqC,UA4JrC,CAAA,EA5JkD,IA4JlD;;;;AAEe;AAkBpB,UArKY,iBAAA,CAqKC;EAKD;;;;;EAsBW,UAAE,CAAA,EAAA,MAAA;EAAa;;AAKxB;AASnB;;;EAA+D,aAAG,CAAA,EAAA,MAAA;AAAI;;;;;;;;;;;;;;;;;;;iBA3KtD,UAAA,OACR,gBACG,oBACR,OAAO;;;;UAsEO,iBAAA;;;;cAIH;;;;;0BAKsB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BpB,aAAA,SACN,0BACC,oBACR,OAAO;KAkBL,aAAA;;;;UAKY,kBAAA;;;;;cAKH,mBAAmB;;;;;;;;;;;;;;;;aAiBpB,OAAO,UAAU;;;;YAKlB;;;;;;;;iBASI,cAAA,WAAwB,qBAA0B"}

package/dist/sink.d.ts

@@ -30,6 +30,44 @@ type Sink = (record: LogRecord) => void;
  * @returns A sink that only logs records that pass the filter.
  */
 declare function withFilter(sink: Sink, filter: FilterLike): Sink;
+/**
+ * Options for the {@link withBuffer} function.
+ * @since 1.0.0
+ */
+interface BufferSinkOptions {
+  /**
+   * The maximum number of log records to buffer before flushing to the
+   * underlying sink.
+   * @default `10`
+   */
+  bufferSize?: number;
+  /**
+   * The maximum time in milliseconds to wait before flushing buffered records
+   * to the underlying sink.  Defaults to 5000 (5 seconds).  Set to 0 or
+   * negative to disable time-based flushing.
+   * @default `5000`
+   */
+  flushInterval?: number;
+}
+/**
+ * Turns a sink into a buffered sink.  The returned sink buffers log records
+ * in memory and flushes them to the underlying sink when the buffer is full
+ * or after a specified time interval.
+ *
+ * @example Buffer a console sink with custom options
+ * ```typescript
+ * const sink = withBuffer(getConsoleSink(), {
+ *   bufferSize: 5,
+ *   flushInterval: 1000
+ * });
+ * ```
+ *
+ * @param sink A sink to be buffered.
+ * @param options Options for the buffered sink.
+ * @returns A buffered sink that flushes records periodically.
+ * @since 1.0.0
+ */
+declare function withBuffer(sink: Sink, options?: BufferSinkOptions): Sink & AsyncDisposable;
 /**
  * Options for the {@link getStreamSink} function.
  */
@@ -109,5 +147,5 @@ interface ConsoleSinkOptions {
  */
 declare function getConsoleSink(options?: ConsoleSinkOptions): Sink;
 //#endregion
-export { ConsoleSinkOptions, Sink, StreamSinkOptions, getConsoleSink, getStreamSink, withFilter };
+export { BufferSinkOptions, ConsoleSinkOptions, Sink, StreamSinkOptions, getConsoleSink, getStreamSink, withBuffer, withFilter };
 //# sourceMappingURL=sink.d.ts.map

package/dist/sink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sink.d.ts","names":[],"sources":["../sink.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAmBA;AAgBA;;;;;AAAgE;AAU/C,KA1BL,IAAA,GA0BK,CAAA,MAAiB,EA1BN,SA0BM,EAAA,GAAA,IAAA;;;;AASY;AA2B9C;;;;;;AAGyB;AAgBxB;AAOD;;AAKc,iBA7EE,UAAA,CA6EF,IAAA,EA7EmB,IA6EnB,EAAA,MAAA,EA7EiC,UA6EjC,CAAA,EA7E8C,IA6E9C;;;;AAiBD,UApFI,iBAAA,CAoFJ;EAAM;AAKA;AASnB;EAA8B,SAAA,CAAA,EA9FhB,aA8FgB;EAAA;;AAAwC;;0BAzFlC;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BpB,aAAA,SACN,0BACC,oBACR,OAAO;KAkBL,aAAA;;;;UAKY,kBAAA;;;;;cAKH,mBAAmB;;;;;;;;;;;;;;;;aAiBpB,OAAO,UAAU;;;;YAKlB;;;;;;;;iBASI,cAAA,WAAwB,qBAA0B"}
+{"version":3,"file":"sink.d.ts","names":[],"sources":["../sink.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAmBA;AAgBA;;;;;AAAgE;AAW/C,KA3BL,IAAA,GA2BK,CAAA,MAAiB,EA3BN,SA2BM,EAAA,GAAA,IAAA;AAmClC;;;;;;AAGyB;AAsEzB;;;;AAS8C;AA2B9C;;AACU,iBA5JM,UAAA,CA4JN,IAAA,EA5JuB,IA4JvB,EAAA,MAAA,EA5JqC,UA4JrC,CAAA,EA5JkD,IA4JlD;;;;AAEe;AAkBpB,UArKY,iBAAA,CAqKC;EAKD;;;;;EAsBW,UAAE,CAAA,EAAA,MAAA;EAAa;;AAKxB;AASnB;;;EAA+D,aAAG,CAAA,EAAA,MAAA;AAAI;;;;;;;;;;;;;;;;;;;iBA3KtD,UAAA,OACR,gBACG,oBACR,OAAO;;;;UAsEO,iBAAA;;;;cAIH;;;;;0BAKsB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BpB,aAAA,SACN,0BACC,oBACR,OAAO;KAkBL,aAAA;;;;UAKY,kBAAA;;;;;cAKH,mBAAmB;;;;;;;;;;;;;;;;aAiBpB,OAAO,UAAU;;;;YAKlB;;;;;;;;iBASI,cAAA,WAAwB,qBAA0B"}

package/dist/sink.js

@@ -23,6 +23,68 @@ function withFilter(sink, filter) {
 	};
 }
 /**
+* Turns a sink into a buffered sink.  The returned sink buffers log records
+* in memory and flushes them to the underlying sink when the buffer is full
+* or after a specified time interval.
+*
+* @example Buffer a console sink with custom options
+* ```typescript
+* const sink = withBuffer(getConsoleSink(), {
+*   bufferSize: 5,
+*   flushInterval: 1000
+* });
+* ```
+*
+* @param sink A sink to be buffered.
+* @param options Options for the buffered sink.
+* @returns A buffered sink that flushes records periodically.
+* @since 1.0.0
+*/
+function withBuffer(sink, options = {}) {
+	const bufferSize = options.bufferSize ?? 10;
+	const flushInterval = options.flushInterval ?? 5e3;
+	const buffer = [];
+	let flushTimer = null;
+	let disposed = false;
+	function flush() {
+		if (buffer.length === 0) return;
+		const records = buffer.splice(0);
+		for (const record of records) try {
+			sink(record);
+		} catch (error) {
+			throw error;
+		}
+		if (flushTimer !== null) {
+			clearTimeout(flushTimer);
+			flushTimer = null;
+		}
+	}
+	function scheduleFlush() {
+		if (flushInterval <= 0 || flushTimer !== null || disposed) return;
+		flushTimer = setTimeout(() => {
+			flushTimer = null;
+			flush();
+		}, flushInterval);
+	}
+	const bufferedSink = (record) => {
+		if (disposed) return;
+		buffer.push(record);
+		if (buffer.length >= bufferSize) flush();
+		else scheduleFlush();
+	};
+	bufferedSink[Symbol.asyncDispose] = async () => {
+		disposed = true;
+		if (flushTimer !== null) {
+			clearTimeout(flushTimer);
+			flushTimer = null;
+		}
+		flush();
+		if (Symbol.asyncDispose in sink) await sink[Symbol.asyncDispose]();
+		else if (Symbol.dispose in sink) sink[Symbol.dispose]();
+	};
+	return bufferedSink;
+}
+/**
 * A factory that returns a sink that writes to a {@link WritableStream}.
 *
 * Note that the `stream` is of Web Streams API, which is different from
@@ -91,5 +153,5 @@ function getConsoleSink(options = {}) {
 }
 
 //#endregion
-export { getConsoleSink, getStreamSink, withFilter };
+export { getConsoleSink, getStreamSink, withBuffer, withFilter };
 //# sourceMappingURL=sink.js.map

package/dist/sink.js.map

@@ -1 +1 @@
-{"version":3,"file":"sink.js","names":["sink: Sink","filter: FilterLike","record: LogRecord","stream: WritableStream","options: StreamSinkOptions","sink: Sink & AsyncDisposable","options: ConsoleSinkOptions","levelMap: Record<LogLevel, ConsoleMethod>"],"sources":["../sink.ts"],"sourcesContent":["import { type FilterLike, toFilter } from \"./filter.ts\";\nimport {\n  type ConsoleFormatter,\n  defaultConsoleFormatter,\n  defaultTextFormatter,\n  type TextFormatter,\n} from \"./formatter.ts\";\nimport type { LogLevel } from \"./level.ts\";\nimport type { LogRecord } from \"./record.ts\";\n\n/**\n * A sink is a function that accepts a log record and prints it somewhere.\n * Thrown exceptions will be suppressed and then logged to the meta logger,\n * a {@link Logger} with the category `[\"logtape\", \"meta\"]`.  (In that case,\n * the meta log record will not be passed to the sink to avoid infinite\n * recursion.)\n *\n * @param record The log record to sink.\n */\nexport type Sink = (record: LogRecord) => void;\n\n/**\n * Turns a sink into a filtered sink.  The returned sink only logs records that\n * pass the filter.\n *\n * @example Filter a console sink to only log records with the info level\n * ```typescript\n * const sink = withFilter(getConsoleSink(), \"info\");\n * ```\n *\n * @param sink A sink to be filtered.\n * @param filter A filter to apply to the sink.  It can be either a filter\n *               function or a {@link LogLevel} string.\n * @returns A sink that only logs records that pass the filter.\n */\nexport function withFilter(sink: Sink, filter: FilterLike): Sink {\n  const filterFunc = toFilter(filter);\n  return (record: LogRecord) => {\n    if (filterFunc(record)) sink(record);\n  };\n}\n\n/**\n * Options for the {@link getStreamSink} function.\n */\nexport interface StreamSinkOptions {\n  /**\n   * The text formatter to use.  Defaults to {@link defaultTextFormatter}.\n   */\n  formatter?: TextFormatter;\n\n  /**\n   * The text encoder to use.  Defaults to an instance of {@link TextEncoder}.\n   */\n  encoder?: { encode(text: string): Uint8Array };\n}\n\n/**\n * A factory that returns a sink that writes to a {@link WritableStream}.\n *\n * Note that the `stream` is of Web Streams API, which is different from\n * Node.js streams.  You can convert a Node.js stream to a Web Streams API\n * stream using [`stream.Writable.toWeb()`] method.\n *\n * [`stream.Writable.toWeb()`]: https://nodejs.org/api/stream.html#streamwritabletowebstreamwritable\n *\n * @example Sink to the standard error in Deno\n * ```typescript\n * const stderrSink = getStreamSink(Deno.stderr.writable);\n * ```\n *\n * @example Sink to the standard error in Node.js\n * ```typescript\n * import stream from \"node:stream\";\n * const stderrSink = getStreamSink(stream.Writable.toWeb(process.stderr));\n * ```\n *\n * @param stream The stream to write to.\n * @param options The options for the sink.\n * @returns A sink that writes to the stream.\n */\nexport function getStreamSink(\n  stream: WritableStream,\n  options: StreamSinkOptions = {},\n): Sink & AsyncDisposable {\n  const formatter = options.formatter ?? defaultTextFormatter;\n  const encoder = options.encoder ?? new TextEncoder();\n  const writer = stream.getWriter();\n  let lastPromise = Promise.resolve();\n  const sink: Sink & AsyncDisposable = (record: LogRecord) => {\n    const bytes = encoder.encode(formatter(record));\n    lastPromise = lastPromise\n      .then(() => writer.ready)\n      .then(() => writer.write(bytes));\n  };\n  sink[Symbol.asyncDispose] = async () => {\n    await lastPromise;\n    await writer.close();\n  };\n  return sink;\n}\n\ntype ConsoleMethod = \"debug\" | \"info\" | \"log\" | \"warn\" | \"error\";\n\n/**\n * Options for the {@link getConsoleSink} function.\n */\nexport interface ConsoleSinkOptions {\n  /**\n   * The console formatter or text formatter to use.\n   * Defaults to {@link defaultConsoleFormatter}.\n   */\n  formatter?: ConsoleFormatter | TextFormatter;\n\n  /**\n   * The mapping from log levels to console methods.  Defaults to:\n   *\n   * ```typescript\n   * {\n   *   trace: \"trace\",\n   *   debug: \"debug\",\n   *   info: \"info\",\n   *   warning: \"warn\",\n   *   error: \"error\",\n   *   fatal: \"error\",\n   * }\n   * ```\n   * @since 0.9.0\n   */\n  levelMap?: Record<LogLevel, ConsoleMethod>;\n\n  /**\n   * The console to log to.  Defaults to {@link console}.\n   */\n  console?: Console;\n}\n\n/**\n * A console sink factory that returns a sink that logs to the console.\n *\n * @param options The options for the sink.\n * @returns A sink that logs to the console.\n */\nexport function getConsoleSink(options: ConsoleSinkOptions = {}): Sink {\n  const formatter = options.formatter ?? defaultConsoleFormatter;\n  const levelMap: Record<LogLevel, ConsoleMethod> = {\n    trace: \"debug\",\n    debug: \"debug\",\n    info: \"info\",\n    warning: \"warn\",\n    error: \"error\",\n    fatal: \"error\",\n    ...(options.levelMap ?? {}),\n  };\n  const console = options.console ?? globalThis.console;\n  return (record: LogRecord) => {\n    const args = formatter(record);\n    const method = levelMap[record.level];\n    if (method === undefined) {\n      throw new TypeError(`Invalid log level: ${record.level}.`);\n    }\n    if (typeof args === \"string\") {\n      const msg = args.replace(/\\r?\\n$/, \"\");\n      console[method](msg);\n    } else {\n      console[method](...args);\n    }\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAmCA,SAAgB,WAAWA,MAAYC,QAA0B;CAC/D,MAAM,aAAa,SAAS,OAAO;AACnC,QAAO,CAACC,WAAsB;AAC5B,MAAI,WAAW,OAAO,CAAE,MAAK,OAAO;CACrC;AACF;;;;;;;;;;;;;;;;;;;;;;;;;AAyCD,SAAgB,cACdC,QACAC,UAA6B,CAAE,GACP;CACxB,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,UAAU,QAAQ,WAAW,IAAI;CACvC,MAAM,SAAS,OAAO,WAAW;CACjC,IAAI,cAAc,QAAQ,SAAS;CACnC,MAAMC,OAA+B,CAACH,WAAsB;EAC1D,MAAM,QAAQ,QAAQ,OAAO,UAAU,OAAO,CAAC;AAC/C,gBAAc,YACX,KAAK,MAAM,OAAO,MAAM,CACxB,KAAK,MAAM,OAAO,MAAM,MAAM,CAAC;CACnC;AACD,MAAK,OAAO,gBAAgB,YAAY;AACtC,QAAM;AACN,QAAM,OAAO,OAAO;CACrB;AACD,QAAO;AACR;;;;;;;AA2CD,SAAgB,eAAeI,UAA8B,CAAE,GAAQ;CACrE,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAMC,WAA4C;EAChD,OAAO;EACP,OAAO;EACP,MAAM;EACN,SAAS;EACT,OAAO;EACP,OAAO;EACP,GAAI,QAAQ,YAAY,CAAE;CAC3B;CACD,MAAM,UAAU,QAAQ,WAAW,WAAW;AAC9C,QAAO,CAACL,WAAsB;EAC5B,MAAM,OAAO,UAAU,OAAO;EAC9B,MAAM,SAAS,SAAS,OAAO;AAC/B,MAAI,kBACF,OAAM,IAAI,WAAW,qBAAqB,OAAO,MAAM;AAEzD,aAAW,SAAS,UAAU;GAC5B,MAAM,MAAM,KAAK,QAAQ,UAAU,GAAG;AACtC,WAAQ,QAAQ,IAAI;EACrB,MACC,SAAQ,QAAQ,GAAG,KAAK;CAE3B;AACF"}
+{"version":3,"file":"sink.js","names":["sink: Sink","filter: FilterLike","record: LogRecord","options: BufferSinkOptions","buffer: LogRecord[]","flushTimer: ReturnType<typeof setTimeout> | null","bufferedSink: Sink & AsyncDisposable","stream: WritableStream","options: StreamSinkOptions","sink: Sink & AsyncDisposable","options: ConsoleSinkOptions","levelMap: Record<LogLevel, ConsoleMethod>"],"sources":["../sink.ts"],"sourcesContent":["import { type FilterLike, toFilter } from \"./filter.ts\";\nimport {\n  type ConsoleFormatter,\n  defaultConsoleFormatter,\n  defaultTextFormatter,\n  type TextFormatter,\n} from \"./formatter.ts\";\nimport type { LogLevel } from \"./level.ts\";\nimport type { LogRecord } from \"./record.ts\";\n\n/**\n * A sink is a function that accepts a log record and prints it somewhere.\n * Thrown exceptions will be suppressed and then logged to the meta logger,\n * a {@link Logger} with the category `[\"logtape\", \"meta\"]`.  (In that case,\n * the meta log record will not be passed to the sink to avoid infinite\n * recursion.)\n *\n * @param record The log record to sink.\n */\nexport type Sink = (record: LogRecord) => void;\n\n/**\n * Turns a sink into a filtered sink.  The returned sink only logs records that\n * pass the filter.\n *\n * @example Filter a console sink to only log records with the info level\n * ```typescript\n * const sink = withFilter(getConsoleSink(), \"info\");\n * ```\n *\n * @param sink A sink to be filtered.\n * @param filter A filter to apply to the sink.  It can be either a filter\n *               function or a {@link LogLevel} string.\n * @returns A sink that only logs records that pass the filter.\n */\nexport function withFilter(sink: Sink, filter: FilterLike): Sink {\n  const filterFunc = toFilter(filter);\n  return (record: LogRecord) => {\n    if (filterFunc(record)) sink(record);\n  };\n}\n\n/**\n * Options for the {@link withBuffer} function.\n * @since 1.0.0\n */\nexport interface BufferSinkOptions {\n  /**\n   * The maximum number of log records to buffer before flushing to the\n   * underlying sink.\n   * @default `10`\n   */\n  bufferSize?: number;\n\n  /**\n   * The maximum time in milliseconds to wait before flushing buffered records\n   * to the underlying sink.  Defaults to 5000 (5 seconds).  Set to 0 or\n   * negative to disable time-based flushing.\n   * @default `5000`\n   */\n  flushInterval?: number;\n}\n\n/**\n * Turns a sink into a buffered sink.  The returned sink buffers log records\n * in memory and flushes them to the underlying sink when the buffer is full\n * or after a specified time interval.\n *\n * @example Buffer a console sink with custom options\n * ```typescript\n * const sink = withBuffer(getConsoleSink(), {\n *   bufferSize: 5,\n *   flushInterval: 1000\n * });\n * ```\n *\n * @param sink A sink to be buffered.\n * @param options Options for the buffered sink.\n * @returns A buffered sink that flushes records periodically.\n * @since 1.0.0\n */\nexport function withBuffer(\n  sink: Sink,\n  options: BufferSinkOptions = {},\n): Sink & AsyncDisposable {\n  const bufferSize = options.bufferSize ?? 10;\n  const flushInterval = options.flushInterval ?? 5000;\n\n  const buffer: LogRecord[] = [];\n  let flushTimer: ReturnType<typeof setTimeout> | null = null;\n  let disposed = false;\n\n  function flush(): void {\n    if (buffer.length === 0) return;\n\n    const records = buffer.splice(0);\n    for (const record of records) {\n      try {\n        sink(record);\n      } catch (error) {\n        // Errors are handled by the sink infrastructure\n        throw error;\n      }\n    }\n\n    if (flushTimer !== null) {\n      clearTimeout(flushTimer);\n      flushTimer = null;\n    }\n  }\n\n  function scheduleFlush(): void {\n    if (flushInterval <= 0 || flushTimer !== null || disposed) return;\n\n    flushTimer = setTimeout(() => {\n      flushTimer = null;\n      flush();\n    }, flushInterval);\n  }\n\n  const bufferedSink: Sink & AsyncDisposable = (record: LogRecord) => {\n    if (disposed) return;\n\n    buffer.push(record);\n\n    if (buffer.length >= bufferSize) {\n      flush();\n    } else {\n      scheduleFlush();\n    }\n  };\n\n  bufferedSink[Symbol.asyncDispose] = async () => {\n    disposed = true;\n    if (flushTimer !== null) {\n      clearTimeout(flushTimer);\n      flushTimer = null;\n    }\n    flush();\n\n    // Dispose the underlying sink if it's disposable\n    if (Symbol.asyncDispose in sink) {\n      await (sink as AsyncDisposable)[Symbol.asyncDispose]();\n    } else if (Symbol.dispose in sink) {\n      (sink as Disposable)[Symbol.dispose]();\n    }\n  };\n\n  return bufferedSink;\n}\n\n/**\n * Options for the {@link getStreamSink} function.\n */\nexport interface StreamSinkOptions {\n  /**\n   * The text formatter to use.  Defaults to {@link defaultTextFormatter}.\n   */\n  formatter?: TextFormatter;\n\n  /**\n   * The text encoder to use.  Defaults to an instance of {@link TextEncoder}.\n   */\n  encoder?: { encode(text: string): Uint8Array };\n}\n\n/**\n * A factory that returns a sink that writes to a {@link WritableStream}.\n *\n * Note that the `stream` is of Web Streams API, which is different from\n * Node.js streams.  You can convert a Node.js stream to a Web Streams API\n * stream using [`stream.Writable.toWeb()`] method.\n *\n * [`stream.Writable.toWeb()`]: https://nodejs.org/api/stream.html#streamwritabletowebstreamwritable\n *\n * @example Sink to the standard error in Deno\n * ```typescript\n * const stderrSink = getStreamSink(Deno.stderr.writable);\n * ```\n *\n * @example Sink to the standard error in Node.js\n * ```typescript\n * import stream from \"node:stream\";\n * const stderrSink = getStreamSink(stream.Writable.toWeb(process.stderr));\n * ```\n *\n * @param stream The stream to write to.\n * @param options The options for the sink.\n * @returns A sink that writes to the stream.\n */\nexport function getStreamSink(\n  stream: WritableStream,\n  options: StreamSinkOptions = {},\n): Sink & AsyncDisposable {\n  const formatter = options.formatter ?? defaultTextFormatter;\n  const encoder = options.encoder ?? new TextEncoder();\n  const writer = stream.getWriter();\n  let lastPromise = Promise.resolve();\n  const sink: Sink & AsyncDisposable = (record: LogRecord) => {\n    const bytes = encoder.encode(formatter(record));\n    lastPromise = lastPromise\n      .then(() => writer.ready)\n      .then(() => writer.write(bytes));\n  };\n  sink[Symbol.asyncDispose] = async () => {\n    await lastPromise;\n    await writer.close();\n  };\n  return sink;\n}\n\ntype ConsoleMethod = \"debug\" | \"info\" | \"log\" | \"warn\" | \"error\";\n\n/**\n * Options for the {@link getConsoleSink} function.\n */\nexport interface ConsoleSinkOptions {\n  /**\n   * The console formatter or text formatter to use.\n   * Defaults to {@link defaultConsoleFormatter}.\n   */\n  formatter?: ConsoleFormatter | TextFormatter;\n\n  /**\n   * The mapping from log levels to console methods.  Defaults to:\n   *\n   * ```typescript\n   * {\n   *   trace: \"trace\",\n   *   debug: \"debug\",\n   *   info: \"info\",\n   *   warning: \"warn\",\n   *   error: \"error\",\n   *   fatal: \"error\",\n   * }\n   * ```\n   * @since 0.9.0\n   */\n  levelMap?: Record<LogLevel, ConsoleMethod>;\n\n  /**\n   * The console to log to.  Defaults to {@link console}.\n   */\n  console?: Console;\n}\n\n/**\n * A console sink factory that returns a sink that logs to the console.\n *\n * @param options The options for the sink.\n * @returns A sink that logs to the console.\n */\nexport function getConsoleSink(options: ConsoleSinkOptions = {}): Sink {\n  const formatter = options.formatter ?? defaultConsoleFormatter;\n  const levelMap: Record<LogLevel, ConsoleMethod> = {\n    trace: \"debug\",\n    debug: \"debug\",\n    info: \"info\",\n    warning: \"warn\",\n    error: \"error\",\n    fatal: \"error\",\n    ...(options.levelMap ?? {}),\n  };\n  const console = options.console ?? globalThis.console;\n  return (record: LogRecord) => {\n    const args = formatter(record);\n    const method = levelMap[record.level];\n    if (method === undefined) {\n      throw new TypeError(`Invalid log level: ${record.level}.`);\n    }\n    if (typeof args === \"string\") {\n      const msg = args.replace(/\\r?\\n$/, \"\");\n      console[method](msg);\n    } else {\n      console[method](...args);\n    }\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAmCA,SAAgB,WAAWA,MAAYC,QAA0B;CAC/D,MAAM,aAAa,SAAS,OAAO;AACnC,QAAO,CAACC,WAAsB;AAC5B,MAAI,WAAW,OAAO,CAAE,MAAK,OAAO;CACrC;AACF;;;;;;;;;;;;;;;;;;;AAyCD,SAAgB,WACdF,MACAG,UAA6B,CAAE,GACP;CACxB,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,gBAAgB,QAAQ,iBAAiB;CAE/C,MAAMC,SAAsB,CAAE;CAC9B,IAAIC,aAAmD;CACvD,IAAI,WAAW;CAEf,SAAS,QAAc;AACrB,MAAI,OAAO,WAAW,EAAG;EAEzB,MAAM,UAAU,OAAO,OAAO,EAAE;AAChC,OAAK,MAAM,UAAU,QACnB,KAAI;AACF,QAAK,OAAO;EACb,SAAQ,OAAO;AAEd,SAAM;EACP;AAGH,MAAI,eAAe,MAAM;AACvB,gBAAa,WAAW;AACxB,gBAAa;EACd;CACF;CAED,SAAS,gBAAsB;AAC7B,MAAI,iBAAiB,KAAK,eAAe,QAAQ,SAAU;AAE3D,eAAa,WAAW,MAAM;AAC5B,gBAAa;AACb,UAAO;EACR,GAAE,cAAc;CAClB;CAED,MAAMC,eAAuC,CAACJ,WAAsB;AAClE,MAAI,SAAU;AAEd,SAAO,KAAK,OAAO;AAEnB,MAAI,OAAO,UAAU,WACnB,QAAO;MAEP,gBAAe;CAElB;AAED,cAAa,OAAO,gBAAgB,YAAY;AAC9C,aAAW;AACX,MAAI,eAAe,MAAM;AACvB,gBAAa,WAAW;AACxB,gBAAa;EACd;AACD,SAAO;AAGP,MAAI,OAAO,gBAAgB,KACzB,OAAM,AAAC,KAAyB,OAAO,eAAe;WAC7C,OAAO,WAAW,KAC3B,CAAC,KAAoB,OAAO,UAAU;CAEzC;AAED,QAAO;AACR;;;;;;;;;;;;;;;;;;;;;;;;;AAyCD,SAAgB,cACdK,QACAC,UAA6B,CAAE,GACP;CACxB,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,UAAU,QAAQ,WAAW,IAAI;CACvC,MAAM,SAAS,OAAO,WAAW;CACjC,IAAI,cAAc,QAAQ,SAAS;CACnC,MAAMC,OAA+B,CAACP,WAAsB;EAC1D,MAAM,QAAQ,QAAQ,OAAO,UAAU,OAAO,CAAC;AAC/C,gBAAc,YACX,KAAK,MAAM,OAAO,MAAM,CACxB,KAAK,MAAM,OAAO,MAAM,MAAM,CAAC;CACnC;AACD,MAAK,OAAO,gBAAgB,YAAY;AACtC,QAAM;AACN,QAAM,OAAO,OAAO;CACrB;AACD,QAAO;AACR;;;;;;;AA2CD,SAAgB,eAAeQ,UAA8B,CAAE,GAAQ;CACrE,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAMC,WAA4C;EAChD,OAAO;EACP,OAAO;EACP,MAAM;EACN,SAAS;EACT,OAAO;EACP,OAAO;EACP,GAAI,QAAQ,YAAY,CAAE;CAC3B;CACD,MAAM,UAAU,QAAQ,WAAW,WAAW;AAC9C,QAAO,CAACT,WAAsB;EAC5B,MAAM,OAAO,UAAU,OAAO;EAC9B,MAAM,SAAS,SAAS,OAAO;AAC/B,MAAI,kBACF,OAAM,IAAI,WAAW,qBAAqB,OAAO,MAAM;AAEzD,aAAW,SAAS,UAAU;GAC5B,MAAM,MAAM,KAAK,QAAQ,UAAU,GAAG;AACtC,WAAQ,QAAQ,IAAI;EACrB,MACC,SAAQ,QAAQ,GAAG,KAAK;CAE3B;AACF"}

package/mod.ts

@@ -44,11 +44,13 @@ export {
 export { getLogger, type Logger, type LogMethod } from "./logger.ts";
 export type { LogRecord } from "./record.ts";
 export {
+  type BufferSinkOptions,
   type ConsoleSinkOptions,
   getConsoleSink,
   getStreamSink,
   type Sink,
   type StreamSinkOptions,
+  withBuffer,
   withFilter,
 } from "./sink.ts";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/logtape",
-  "version": "1.0.0-dev.207+2b6ea0e4",
+  "version": "1.0.0-dev.208+b3f9fea2",
   "description": "Simple logging library with zero dependencies for Deno/Node.js/Bun/browsers",
   "keywords": [
     "logging",

package/sink.test.ts

@@ -1,12 +1,20 @@
 import { suite } from "@alinea/suite";
 import { assertEquals } from "@std/assert/equals";
+import { assertInstanceOf } from "@std/assert/instance-of";
 import { assertThrows } from "@std/assert/throws";
+import { delay } from "@std/async/delay";
 import makeConsoleMock from "consolemock";
 import { debug, error, fatal, info, trace, warning } from "./fixtures.ts";
 import { defaultTextFormatter } from "./formatter.ts";
 import type { LogLevel } from "./level.ts";
 import type { LogRecord } from "./record.ts";
-import { getConsoleSink, getStreamSink, withFilter } from "./sink.ts";
+import {
+  getConsoleSink,
+  getStreamSink,
+  type Sink,
+  withBuffer,
+  withFilter,
+} from "./sink.ts";
 
 const test = suite(import.meta);
 
@@ -246,3 +254,384 @@ test("getConsoleSink()", () => {
     },
   ]);
 });
+
+test("withBuffer() - buffer size limit", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), { bufferSize: 3 });
+
+  // Add records one by one
+  sink(trace);
+  assertEquals(buffer.length, 0); // Not flushed yet
+
+  sink(debug);
+  assertEquals(buffer.length, 0); // Not flushed yet
+
+  sink(info);
+  assertEquals(buffer.length, 3); // Flushed when buffer is full
+  assertEquals(buffer, [trace, debug, info]);
+
+  // Add more records
+  sink(warning);
+  assertEquals(buffer.length, 3); // Previous records remain
+
+  sink(error);
+  assertEquals(buffer.length, 3); // Still not flushed
+
+  sink(fatal);
+  assertEquals(buffer.length, 6); // Flushed again
+  assertEquals(buffer, [trace, debug, info, warning, error, fatal]);
+
+  await sink[Symbol.asyncDispose]();
+});
+
+test("withBuffer() - flush interval", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), {
+    bufferSize: 10,
+    flushInterval: 100,
+  });
+
+  sink(trace);
+  assertEquals(buffer.length, 0); // Not flushed immediately
+
+  // Wait for flush interval
+  await delay(150);
+  assertEquals(buffer.length, 1); // Flushed after interval
+  assertEquals(buffer, [trace]);
+
+  await sink[Symbol.asyncDispose]();
+});
+
+test("withBuffer() - dispose flushes remaining records", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), { bufferSize: 10 });
+
+  sink(trace);
+  sink(debug);
+  assertEquals(buffer.length, 0); // Not flushed yet
+
+  await sink[Symbol.asyncDispose]();
+  assertEquals(buffer.length, 2); // Flushed on dispose
+  assertEquals(buffer, [trace, debug]);
+});
+
+test("withBuffer() - disabled flush interval", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), {
+    bufferSize: 10,
+    flushInterval: 0,
+  });
+
+  sink(trace);
+  assertEquals(buffer.length, 0); // Not flushed immediately
+
+  // Wait longer than normal flush interval
+  await delay(200);
+  assertEquals(buffer.length, 0); // Still not flushed due to disabled interval
+
+  await sink[Symbol.asyncDispose]();
+  assertEquals(buffer.length, 1); // Flushed only on dispose
+  assertEquals(buffer, [trace]);
+});
+
+test("withBuffer() - default options", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer));
+
+  // Add 9 records (less than default buffer size of 10)
+  for (let i = 0; i < 9; i++) {
+    sink(trace);
+  }
+  assertEquals(buffer.length, 0); // Not flushed yet
+
+  // Add 10th record to trigger flush
+  sink(trace);
+  assertEquals(buffer.length, 10); // Flushed when buffer is full
+
+  await sink[Symbol.asyncDispose]();
+});
+
+test("withBuffer() - no operation after dispose", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), { bufferSize: 3 });
+
+  await sink[Symbol.asyncDispose]();
+
+  // Try to add records after dispose
+  sink(trace);
+  sink(debug);
+  assertEquals(buffer.length, 0); // No records added after dispose
+});
+
+test("withBuffer() - disposes underlying AsyncDisposable sink", async () => {
+  const buffer: LogRecord[] = [];
+  let disposed = false;
+
+  const disposableSink: Sink & AsyncDisposable = (record: LogRecord) => {
+    buffer.push(record);
+  };
+  disposableSink[Symbol.asyncDispose] = () => {
+    disposed = true;
+    return Promise.resolve();
+  };
+
+  const bufferedSink = withBuffer(disposableSink);
+
+  await bufferedSink[Symbol.asyncDispose]();
+
+  assertEquals(disposed, true); // Underlying sink should be disposed
+});
+
+test("withBuffer() - disposes underlying Disposable sink", async () => {
+  const buffer: LogRecord[] = [];
+  let disposed = false;
+
+  const disposableSink: Sink & Disposable = (record: LogRecord) => {
+    buffer.push(record);
+  };
+  disposableSink[Symbol.dispose] = () => {
+    disposed = true;
+  };
+
+  const bufferedSink = withBuffer(disposableSink);
+
+  await bufferedSink[Symbol.asyncDispose]();
+
+  assertEquals(disposed, true); // Underlying sink should be disposed
+});
+
+test("withBuffer() - handles non-disposable sink gracefully", async () => {
+  const buffer: LogRecord[] = [];
+  const regularSink: Sink = (record: LogRecord) => {
+    buffer.push(record);
+  };
+
+  const bufferedSink = withBuffer(regularSink);
+
+  // Should not throw when disposing non-disposable sink
+  await bufferedSink[Symbol.asyncDispose]();
+
+  // This test passes if no error is thrown
+  assertEquals(true, true);
+});
+
+test("withBuffer() - edge case: bufferSize 1", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), { bufferSize: 1 });
+
+  // Every record should flush immediately
+  sink(trace);
+  assertEquals(buffer.length, 1);
+  assertEquals(buffer, [trace]);
+
+  sink(debug);
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer, [trace, debug]);
+
+  await sink[Symbol.asyncDispose]();
+});
+
+test("withBuffer() - edge case: bufferSize 0 or negative", async () => {
+  const buffer: LogRecord[] = [];
+  const sink1 = withBuffer(buffer.push.bind(buffer), { bufferSize: 0 });
+  const sink2 = withBuffer(buffer.push.bind(buffer), { bufferSize: -5 });
+
+  // Should still work, but behavior may vary
+  sink1(trace);
+  sink2(debug);
+
+  await sink1[Symbol.asyncDispose]();
+  await sink2[Symbol.asyncDispose]();
+
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer, [trace, debug]);
+});
+
+test("withBuffer() - edge case: very large bufferSize", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), { bufferSize: 10000 });
+
+  // Add many records without hitting buffer limit
+  for (let i = 0; i < 100; i++) {
+    sink(trace);
+  }
+  assertEquals(buffer.length, 0); // Not flushed yet
+
+  await sink[Symbol.asyncDispose]();
+  assertEquals(buffer.length, 100); // All flushed on dispose
+});
+
+test("withBuffer() - edge case: rapid successive calls", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), { bufferSize: 3 });
+
+  // Add records in rapid succession
+  sink(trace);
+  sink(debug);
+  sink(info); // This should trigger flush
+  sink(warning);
+  sink(error);
+  sink(fatal); // This should trigger another flush
+
+  assertEquals(buffer.length, 6);
+  assertEquals(buffer, [trace, debug, info, warning, error, fatal]);
+
+  await sink[Symbol.asyncDispose]();
+});
+
+test("withBuffer() - edge case: multiple timer flushes", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), {
+    bufferSize: 10,
+    flushInterval: 50,
+  });
+
+  sink(trace);
+  await delay(60);
+  assertEquals(buffer.length, 1); // First flush
+
+  sink(debug);
+  await delay(60);
+  assertEquals(buffer.length, 2); // Second flush
+
+  sink(info);
+  await delay(60);
+  assertEquals(buffer.length, 3); // Third flush
+
+  await sink[Symbol.asyncDispose]();
+});
+
+test("withBuffer() - edge case: timer and buffer size interaction", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), {
+    bufferSize: 3,
+    flushInterval: 100,
+  });
+
+  // Add 2 records (less than bufferSize)
+  sink(trace);
+  sink(debug);
+  assertEquals(buffer.length, 0);
+
+  // Wait for timer flush
+  await delay(120);
+  assertEquals(buffer.length, 2); // Timer flush
+
+  // Add 3 more records to trigger buffer flush
+  sink(info);
+  sink(warning);
+  sink(error); // Should trigger immediate flush
+  assertEquals(buffer.length, 5);
+
+  await sink[Symbol.asyncDispose]();
+});
+
+test("withBuffer() - edge case: dispose called multiple times", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), { bufferSize: 10 });
+
+  sink(trace);
+  sink(debug);
+
+  // First dispose
+  await sink[Symbol.asyncDispose]();
+  assertEquals(buffer.length, 2);
+
+  // Second dispose - should not cause errors or duplicate records
+  await sink[Symbol.asyncDispose]();
+  assertEquals(buffer.length, 2); // Should remain the same
+
+  // Third dispose
+  await sink[Symbol.asyncDispose]();
+  assertEquals(buffer.length, 2); // Should remain the same
+});
+
+test("withBuffer() - edge case: underlying sink throws error", async () => {
+  let errorCount = 0;
+  const errorSink: Sink = () => {
+    errorCount++;
+    throw new Error("Sink error");
+  };
+
+  const bufferedSink = withBuffer(errorSink, { bufferSize: 2 });
+
+  // First record goes to buffer
+  bufferedSink(trace);
+
+  // Second record should trigger flush and throw error
+  try {
+    bufferedSink(debug);
+    // Should not reach here
+    assertEquals(true, false, "Expected error to be thrown");
+  } catch (error) {
+    assertInstanceOf(error, Error);
+    assertEquals(error.message, "Sink error");
+    assertEquals(errorCount, 1); // Only first record processed before error
+  }
+
+  await bufferedSink[Symbol.asyncDispose]();
+});
+
+test("withBuffer() - edge case: underlying AsyncDisposable throws error", async () => {
+  const buffer: LogRecord[] = [];
+  let disposed = false;
+
+  const errorDisposableSink: Sink & AsyncDisposable = (record: LogRecord) => {
+    buffer.push(record);
+  };
+  errorDisposableSink[Symbol.asyncDispose] = () => {
+    disposed = true;
+    throw new Error("Dispose error");
+  };
+
+  const bufferedSink = withBuffer(errorDisposableSink);
+
+  bufferedSink(trace);
+
+  try {
+    await bufferedSink[Symbol.asyncDispose]();
+    // Should not reach here
+    assertEquals(true, false, "Expected dispose error to be thrown");
+  } catch (error) {
+    assertInstanceOf(error, Error);
+    assertEquals(error.message, "Dispose error");
+    assertEquals(disposed, true); // Should still be disposed
+    assertEquals(buffer.length, 1); // Buffer should have been flushed before dispose error
+  }
+});
+
+test("withBuffer() - edge case: negative flushInterval", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), {
+    bufferSize: 10,
+    flushInterval: -1000,
+  });
+
+  sink(trace);
+  assertEquals(buffer.length, 0);
+
+  // Wait longer than a normal flush interval
+  await delay(200);
+  assertEquals(buffer.length, 0); // Should not flush due to negative interval
+
+  await sink[Symbol.asyncDispose]();
+  assertEquals(buffer.length, 1); // Should only flush on dispose
+});
+
+test("withBuffer() - edge case: concurrent dispose and log calls", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = withBuffer(buffer.push.bind(buffer), { bufferSize: 10 });
+
+  sink(trace);
+
+  // Start dispose and immediately try to log more
+  const disposePromise = sink[Symbol.asyncDispose]();
+  sink(debug); // This should be ignored since dispose is in progress
+  sink(info); // This should be ignored since dispose is in progress
+
+  await disposePromise;
+
+  // Only the first record should be in buffer
+  assertEquals(buffer.length, 1);
+  assertEquals(buffer, [trace]);
+});

package/sink.ts

@@ -40,6 +40,115 @@ export function withFilter(sink: Sink, filter: FilterLike): Sink {
   };
 }
 
+/**
+ * Options for the {@link withBuffer} function.
+ * @since 1.0.0
+ */
+export interface BufferSinkOptions {
+  /**
+   * The maximum number of log records to buffer before flushing to the
+   * underlying sink.
+   * @default `10`
+   */
+  bufferSize?: number;
+
+  /**
+   * The maximum time in milliseconds to wait before flushing buffered records
+   * to the underlying sink.  Defaults to 5000 (5 seconds).  Set to 0 or
+   * negative to disable time-based flushing.
+   * @default `5000`
+   */
+  flushInterval?: number;
+}
+
+/**
+ * Turns a sink into a buffered sink.  The returned sink buffers log records
+ * in memory and flushes them to the underlying sink when the buffer is full
+ * or after a specified time interval.
+ *
+ * @example Buffer a console sink with custom options
+ * ```typescript
+ * const sink = withBuffer(getConsoleSink(), {
+ *   bufferSize: 5,
+ *   flushInterval: 1000
+ * });
+ * ```
+ *
+ * @param sink A sink to be buffered.
+ * @param options Options for the buffered sink.
+ * @returns A buffered sink that flushes records periodically.
+ * @since 1.0.0
+ */
+export function withBuffer(
+  sink: Sink,
+  options: BufferSinkOptions = {},
+): Sink & AsyncDisposable {
+  const bufferSize = options.bufferSize ?? 10;
+  const flushInterval = options.flushInterval ?? 5000;
+
+  const buffer: LogRecord[] = [];
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  let disposed = false;
+
+  function flush(): void {
+    if (buffer.length === 0) return;
+
+    const records = buffer.splice(0);
+    for (const record of records) {
+      try {
+        sink(record);
+      } catch (error) {
+        // Errors are handled by the sink infrastructure
+        throw error;
+      }
+    }
+
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+  }
+
+  function scheduleFlush(): void {
+    if (flushInterval <= 0 || flushTimer !== null || disposed) return;
+
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      flush();
+    }, flushInterval);
+  }
+
+  const bufferedSink: Sink & AsyncDisposable = (record: LogRecord) => {
+    if (disposed) return;
+
+    buffer.push(record);
+
+    if (buffer.length >= bufferSize) {
+      flush();
+    } else {
+      scheduleFlush();
+    }
+  };
+
+  bufferedSink[Symbol.asyncDispose] = async () => {
+    disposed = true;
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    flush();
+
+    // Dispose the underlying sink if it's disposable
+    if (Symbol.asyncDispose in sink) {
+      await (sink as AsyncDisposable)[Symbol.asyncDispose]();
+    } else if (Symbol.dispose in sink) {
+      (sink as Disposable)[Symbol.dispose]();
+    }
+  };
+
+  return bufferedSink;
+}
+
 /**
  * Options for the {@link getStreamSink} function.
  */