@logtape/logtape 1.1.0 → 1.2.0-dev.341

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/logtape",
-  "version": "1.1.0",
+  "version": "1.2.0-dev.341+a87baf94",
   "license": "MIT",
   "exports": "./src/mod.ts",
   "imports": {

package/dist/sink.cjs

@@ -256,6 +256,7 @@ function fingersCrossed(sink, options = {}) {
 	const triggerLevel = options.triggerLevel ?? "error";
 	const maxBufferSize = Math.max(0, options.maxBufferSize ?? 1e3);
 	const isolateByCategory = options.isolateByCategory;
+	const isolateByContext = options.isolateByContext;
 	try {
 		require_level.compareLogLevel("trace", triggerLevel);
 	} catch (error) {
@@ -290,7 +291,36 @@ function fingersCrossed(sink, options = {}) {
 	function parseCategoryKey(key) {
 		return JSON.parse(key);
 	}
-	if (!isolateByCategory) {
+	function getContextKey(properties) {
+		if (!isolateByContext || isolateByContext.keys.length === 0) return "";
+		const contextValues = {};
+		for (const key of isolateByContext.keys) if (key in properties) contextValues[key] = properties[key];
+		return JSON.stringify(contextValues);
+	}
+	function getBufferKey(category, properties) {
+		const categoryKey = getCategoryKey(category);
+		if (!isolateByContext) return categoryKey;
+		const contextKey = getContextKey(properties);
+		return `${categoryKey}:${contextKey}`;
+	}
+	function parseBufferKey(key) {
+		if (!isolateByContext) return {
+			category: parseCategoryKey(key),
+			context: ""
+		};
+		const separatorIndex = key.indexOf("]:");
+		if (separatorIndex === -1) return {
+			category: parseCategoryKey(key),
+			context: ""
+		};
+		const categoryPart = key.substring(0, separatorIndex + 1);
+		const contextPart = key.substring(separatorIndex + 2);
+		return {
+			category: parseCategoryKey(categoryPart),
+			context: contextPart
+		};
+	}
+	if (!isolateByCategory && !isolateByContext) {
 		const buffer = [];
 		let triggered = false;
 		return (record) => {
@@ -312,19 +342,26 @@ function fingersCrossed(sink, options = {}) {
 		const buffers = /* @__PURE__ */ new Map();
 		const triggered = /* @__PURE__ */ new Set();
 		return (record) => {
-			const categoryKey = getCategoryKey(record.category);
-			if (triggered.has(categoryKey)) {
+			const bufferKey = getBufferKey(record.category, record.properties);
+			if (triggered.has(bufferKey)) {
 				sink(record);
 				return;
 			}
 			if (require_level.compareLogLevel(record.level, triggerLevel) >= 0) {
 				const keysToFlush = /* @__PURE__ */ new Set();
-				for (const [bufferedKey] of buffers) if (bufferedKey === categoryKey) keysToFlush.add(bufferedKey);
-				else if (shouldFlushBuffer) {
-					const bufferedCategory = parseCategoryKey(bufferedKey);
-					try {
-						if (shouldFlushBuffer(record.category, bufferedCategory)) keysToFlush.add(bufferedKey);
+				for (const [bufferedKey] of buffers) if (bufferedKey === bufferKey) keysToFlush.add(bufferedKey);
+				else {
+					const { category: bufferedCategory, context: bufferedContext } = parseBufferKey(bufferedKey);
+					const { context: triggerContext } = parseBufferKey(bufferKey);
+					let contextMatches = true;
+					if (isolateByContext) contextMatches = bufferedContext === triggerContext;
+					let categoryMatches = false;
+					if (!isolateByCategory) categoryMatches = contextMatches;
+					else if (shouldFlushBuffer) try {
+						categoryMatches = shouldFlushBuffer(record.category, bufferedCategory);
 					} catch {}
+					else categoryMatches = getCategoryKey(record.category) === getCategoryKey(bufferedCategory);
+					if (contextMatches && categoryMatches) keysToFlush.add(bufferedKey);
 				}
 				const allRecordsToFlush = [];
 				for (const key of keysToFlush) {
@@ -337,13 +374,13 @@ function fingersCrossed(sink, options = {}) {
 				}
 				allRecordsToFlush.sort((a, b) => a.timestamp - b.timestamp);
 				for (const bufferedRecord of allRecordsToFlush) sink(bufferedRecord);
-				triggered.add(categoryKey);
+				triggered.add(bufferKey);
 				sink(record);
 			} else {
-				let buffer = buffers.get(categoryKey);
+				let buffer = buffers.get(bufferKey);
 				if (!buffer) {
 					buffer = [];
-					buffers.set(categoryKey, buffer);
+					buffers.set(bufferKey, buffer);
 				}
 				buffer.push(record);
 				while (buffer.length > maxBufferSize) buffer.shift();

package/dist/sink.d.cts

@@ -244,6 +244,37 @@ interface FingersCrossedOptions {
    * @default `undefined` (no isolation, single global buffer)
    */
   readonly isolateByCategory?: "descendant" | "ancestor" | "both" | ((triggerCategory: readonly string[], bufferedCategory: readonly string[]) => boolean);
+  /**
+   * Enable context-based buffer isolation.
+   * When enabled, buffers are isolated based on specified context keys.
+   * This is useful for scenarios like HTTP request tracing where logs
+   * should be isolated per request.
+   *
+   * @example
+   * ```typescript
+   * fingersCrossed(sink, {
+   *   isolateByContext: { keys: ['requestId'] }
+   * })
+   * ```
+   *
+   * @example Combined with category isolation
+   * ```typescript
+   * fingersCrossed(sink, {
+   *   isolateByCategory: 'descendant',
+   *   isolateByContext: { keys: ['requestId', 'sessionId'] }
+   * })
+   * ```
+   *
+   * @default `undefined` (no context isolation)
+   * @since 1.2.0
+   */
+  readonly isolateByContext?: {
+    /**
+     * Context keys to use for isolation.
+     * Buffers will be separate for different combinations of these context values.
+     */
+    readonly keys: readonly string[];
+  };
 }
 /**
  * Creates a sink that buffers log records until a trigger level is reached.

package/dist/sink.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"sink.d.cts","names":[],"sources":["../src/sink.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAmBA;AAWA;;;;AAAsD;AAgBtD;AAA0B,KA3Bd,IAAA,GA2Bc,CAAA,MAAA,EA3BE,SA2BF,EAAA,GAAA,IAAA;;;;AAAsC;AAUhE;;;;AAS8C;AA+D9B,KAlGJ,SAAA,GAkGiB,CAAA,MAAA,EAlGI,SAkGJ,EAAA,GAlGkB,OAkGlB,CAAA,IAAA,CAAA;;;;;;AAGJ;AAgGxB;AAOD;;;;;;;AA2BY,iBAvNI,UAAA,CAuNJ,IAAA,EAvNqB,IAuNrB,EAAA,MAAA,EAvNmC,UAuNnC,CAAA,EAvNgD,IAuNhD;AAAO;AA8CnB;;AACW,UA5PM,iBAAA,CA4PN;EAAuB;;;EACN,SAAA,CAAA,EAzPd,aAyPc;EA4HZ;;;EAAkC,OAAG,CAAA,EAAA;IAAO,MAAA,CAAA,IAAA,EAAA,MAAA,CAAA,EAhXxB,UAgXwB;EAAe,CAAA;EAmB1D;AA8EjB;;;;;AAGO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBArZS,aAAA,SACN,0BACC,oBACR,OAAO;KAkGL,aAAA;;;;UAKY,kBAAA;;;;;cAKH,mBAAmB;;;;;;;;;;;;;;;;aAiBpB,OAAO,UAAU;;;;YAKlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8CI,cAAA,WACL,qBACR,QAAQ,OAAO;;;;;;;;;;;;;;;;;;;;;iBA4HF,aAAA,YAAyB,YAAY,OAAO;;;;;UAmB3C,qBAAA;;;;;;;0BAOS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuEV,cAAA,OACR,gBACG,wBACR"}
+{"version":3,"file":"sink.d.cts","names":[],"sources":["../src/sink.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAmBA;AAWA;;;;AAAsD;AAgBtD;AAA0B,KA3Bd,IAAA,GA2Bc,CAAA,MAAA,EA3BE,SA2BF,EAAA,GAAA,IAAA;;;;AAAsC;AAUhE;;;;AAS8C;AA+D9B,KAlGJ,SAAA,GAkGiB,CAAA,MAAA,EAlGI,SAkGJ,EAAA,GAlGkB,OAkGlB,CAAA,IAAA,CAAA;;;;;;AAGJ;AAgGxB;AAOD;;;;;;;AA2BY,iBAvNI,UAAA,CAuNJ,IAAA,EAvNqB,IAuNrB,EAAA,MAAA,EAvNmC,UAuNnC,CAAA,EAvNgD,IAuNhD;AAAO;AA8CnB;;AACW,UA5PM,iBAAA,CA4PN;EAAuB;;;EACN,SAAA,CAAA,EAzPd,aAyPc;EA4HZ;;;EAAkC,OAAG,CAAA,EAAA;IAAO,MAAA,CAAA,IAAA,EAAA,MAAA,CAAA,EAhXxB,UAgXwB;EAAe,CAAA;EAmB1D;AA8GjB;;;;;AAGO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBArbS,aAAA,SACN,0BACC,oBACR,OAAO;KAkGL,aAAA;;;;UAKY,kBAAA;;;;;cAKH,mBAAmB;;;;;;;;;;;;;;;;aAiBpB,OAAO,UAAU;;;;YAKlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8CI,cAAA,WACL,qBACR,QAAQ,OAAO;;;;;;;;;;;;;;;;;;;;;iBA4HF,aAAA,YAAyB,YAAY,OAAO;;;;;UAmB3C,qBAAA;;;;;;;0BAOS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuGV,cAAA,OACR,gBACG,wBACR"}

package/dist/sink.d.ts

@@ -244,6 +244,37 @@ interface FingersCrossedOptions {
    * @default `undefined` (no isolation, single global buffer)
    */
   readonly isolateByCategory?: "descendant" | "ancestor" | "both" | ((triggerCategory: readonly string[], bufferedCategory: readonly string[]) => boolean);
+  /**
+   * Enable context-based buffer isolation.
+   * When enabled, buffers are isolated based on specified context keys.
+   * This is useful for scenarios like HTTP request tracing where logs
+   * should be isolated per request.
+   *
+   * @example
+   * ```typescript
+   * fingersCrossed(sink, {
+   *   isolateByContext: { keys: ['requestId'] }
+   * })
+   * ```
+   *
+   * @example Combined with category isolation
+   * ```typescript
+   * fingersCrossed(sink, {
+   *   isolateByCategory: 'descendant',
+   *   isolateByContext: { keys: ['requestId', 'sessionId'] }
+   * })
+   * ```
+   *
+   * @default `undefined` (no context isolation)
+   * @since 1.2.0
+   */
+  readonly isolateByContext?: {
+    /**
+     * Context keys to use for isolation.
+     * Buffers will be separate for different combinations of these context values.
+     */
+    readonly keys: readonly string[];
+  };
 }
 /**
  * Creates a sink that buffers log records until a trigger level is reached.

package/dist/sink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sink.d.ts","names":[],"sources":["../src/sink.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAmBA;AAWA;;;;AAAsD;AAgBtD;AAA0B,KA3Bd,IAAA,GA2Bc,CAAA,MAAA,EA3BE,SA2BF,EAAA,GAAA,IAAA;;;;AAAsC;AAUhE;;;;AAS8C;AA+D9B,KAlGJ,SAAA,GAkGiB,CAAA,MAAA,EAlGI,SAkGJ,EAAA,GAlGkB,OAkGlB,CAAA,IAAA,CAAA;;;;;;AAGJ;AAgGxB;AAOD;;;;;;;AA2BY,iBAvNI,UAAA,CAuNJ,IAAA,EAvNqB,IAuNrB,EAAA,MAAA,EAvNmC,UAuNnC,CAAA,EAvNgD,IAuNhD;AAAO;AA8CnB;;AACW,UA5PM,iBAAA,CA4PN;EAAuB;;;EACN,SAAA,CAAA,EAzPd,aAyPc;EA4HZ;;;EAAkC,OAAG,CAAA,EAAA;IAAO,MAAA,CAAA,IAAA,EAAA,MAAA,CAAA,EAhXxB,UAgXwB;EAAe,CAAA;EAmB1D;AA8EjB;;;;;AAGO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBArZS,aAAA,SACN,0BACC,oBACR,OAAO;KAkGL,aAAA;;;;UAKY,kBAAA;;;;;cAKH,mBAAmB;;;;;;;;;;;;;;;;aAiBpB,OAAO,UAAU;;;;YAKlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8CI,cAAA,WACL,qBACR,QAAQ,OAAO;;;;;;;;;;;;;;;;;;;;;iBA4HF,aAAA,YAAyB,YAAY,OAAO;;;;;UAmB3C,qBAAA;;;;;;;0BAOS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuEV,cAAA,OACR,gBACG,wBACR"}
+{"version":3,"file":"sink.d.ts","names":[],"sources":["../src/sink.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAmBA;AAWA;;;;AAAsD;AAgBtD;AAA0B,KA3Bd,IAAA,GA2Bc,CAAA,MAAA,EA3BE,SA2BF,EAAA,GAAA,IAAA;;;;AAAsC;AAUhE;;;;AAS8C;AA+D9B,KAlGJ,SAAA,GAkGiB,CAAA,MAAA,EAlGI,SAkGJ,EAAA,GAlGkB,OAkGlB,CAAA,IAAA,CAAA;;;;;;AAGJ;AAgGxB;AAOD;;;;;;;AA2BY,iBAvNI,UAAA,CAuNJ,IAAA,EAvNqB,IAuNrB,EAAA,MAAA,EAvNmC,UAuNnC,CAAA,EAvNgD,IAuNhD;AAAO;AA8CnB;;AACW,UA5PM,iBAAA,CA4PN;EAAuB;;;EACN,SAAA,CAAA,EAzPd,aAyPc;EA4HZ;;;EAAkC,OAAG,CAAA,EAAA;IAAO,MAAA,CAAA,IAAA,EAAA,MAAA,CAAA,EAhXxB,UAgXwB;EAAe,CAAA;EAmB1D;AA8GjB;;;;;AAGO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBArbS,aAAA,SACN,0BACC,oBACR,OAAO;KAkGL,aAAA;;;;UAKY,kBAAA;;;;;cAKH,mBAAmB;;;;;;;;;;;;;;;;aAiBpB,OAAO,UAAU;;;;YAKlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8CI,cAAA,WACL,qBACR,QAAQ,OAAO;;;;;;;;;;;;;;;;;;;;;iBA4HF,aAAA,YAAyB,YAAY,OAAO;;;;;UAmB3C,qBAAA;;;;;;;0BAOS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuGV,cAAA,OACR,gBACG,wBACR"}

package/dist/sink.js

@@ -256,6 +256,7 @@ function fingersCrossed(sink, options = {}) {
 	const triggerLevel = options.triggerLevel ?? "error";
 	const maxBufferSize = Math.max(0, options.maxBufferSize ?? 1e3);
 	const isolateByCategory = options.isolateByCategory;
+	const isolateByContext = options.isolateByContext;
 	try {
 		compareLogLevel("trace", triggerLevel);
 	} catch (error) {
@@ -290,7 +291,36 @@ function fingersCrossed(sink, options = {}) {
 	function parseCategoryKey(key) {
 		return JSON.parse(key);
 	}
-	if (!isolateByCategory) {
+	function getContextKey(properties) {
+		if (!isolateByContext || isolateByContext.keys.length === 0) return "";
+		const contextValues = {};
+		for (const key of isolateByContext.keys) if (key in properties) contextValues[key] = properties[key];
+		return JSON.stringify(contextValues);
+	}
+	function getBufferKey(category, properties) {
+		const categoryKey = getCategoryKey(category);
+		if (!isolateByContext) return categoryKey;
+		const contextKey = getContextKey(properties);
+		return `${categoryKey}:${contextKey}`;
+	}
+	function parseBufferKey(key) {
+		if (!isolateByContext) return {
+			category: parseCategoryKey(key),
+			context: ""
+		};
+		const separatorIndex = key.indexOf("]:");
+		if (separatorIndex === -1) return {
+			category: parseCategoryKey(key),
+			context: ""
+		};
+		const categoryPart = key.substring(0, separatorIndex + 1);
+		const contextPart = key.substring(separatorIndex + 2);
+		return {
+			category: parseCategoryKey(categoryPart),
+			context: contextPart
+		};
+	}
+	if (!isolateByCategory && !isolateByContext) {
 		const buffer = [];
 		let triggered = false;
 		return (record) => {
@@ -312,19 +342,26 @@ function fingersCrossed(sink, options = {}) {
 		const buffers = /* @__PURE__ */ new Map();
 		const triggered = /* @__PURE__ */ new Set();
 		return (record) => {
-			const categoryKey = getCategoryKey(record.category);
-			if (triggered.has(categoryKey)) {
+			const bufferKey = getBufferKey(record.category, record.properties);
+			if (triggered.has(bufferKey)) {
 				sink(record);
 				return;
 			}
 			if (compareLogLevel(record.level, triggerLevel) >= 0) {
 				const keysToFlush = /* @__PURE__ */ new Set();
-				for (const [bufferedKey] of buffers) if (bufferedKey === categoryKey) keysToFlush.add(bufferedKey);
-				else if (shouldFlushBuffer) {
-					const bufferedCategory = parseCategoryKey(bufferedKey);
-					try {
-						if (shouldFlushBuffer(record.category, bufferedCategory)) keysToFlush.add(bufferedKey);
+				for (const [bufferedKey] of buffers) if (bufferedKey === bufferKey) keysToFlush.add(bufferedKey);
+				else {
+					const { category: bufferedCategory, context: bufferedContext } = parseBufferKey(bufferedKey);
+					const { context: triggerContext } = parseBufferKey(bufferKey);
+					let contextMatches = true;
+					if (isolateByContext) contextMatches = bufferedContext === triggerContext;
+					let categoryMatches = false;
+					if (!isolateByCategory) categoryMatches = contextMatches;
+					else if (shouldFlushBuffer) try {
+						categoryMatches = shouldFlushBuffer(record.category, bufferedCategory);
 					} catch {}
+					else categoryMatches = getCategoryKey(record.category) === getCategoryKey(bufferedCategory);
+					if (contextMatches && categoryMatches) keysToFlush.add(bufferedKey);
 				}
 				const allRecordsToFlush = [];
 				for (const key of keysToFlush) {
@@ -337,13 +374,13 @@ function fingersCrossed(sink, options = {}) {
 				}
 				allRecordsToFlush.sort((a, b) => a.timestamp - b.timestamp);
 				for (const bufferedRecord of allRecordsToFlush) sink(bufferedRecord);
-				triggered.add(categoryKey);
+				triggered.add(bufferKey);
 				sink(record);
 			} else {
-				let buffer = buffers.get(categoryKey);
+				let buffer = buffers.get(bufferKey);
 				if (!buffer) {
 					buffer = [];
-					buffers.set(categoryKey, buffer);
+					buffers.set(bufferKey, buffer);
 				}
 				buffer.push(record);
 				while (buffer.length > maxBufferSize) buffer.shift();

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","buffer: LogRecord[]","flushTimer: ReturnType<typeof setInterval> | null","activeFlush: Promise<void> | null","nonBlockingSink: Sink & AsyncDisposable","options: ConsoleSinkOptions","levelMap: Record<LogLevel, ConsoleMethod>","nonBlockingSink: Sink & Disposable","asyncSink: AsyncSink","options: FingersCrossedOptions","parent: readonly string[]","child: readonly string[]","shouldFlushBuffer:\n    | ((\n      triggerCategory: readonly string[],\n      bufferedCategory: readonly string[],\n    ) => boolean)\n    | null","category: readonly string[]","key: string","allRecordsToFlush: LogRecord[]"],"sources":["../src/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 { compareLogLevel, 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 * An async sink is a function that accepts a log record and asynchronously\n * processes it. This type is used with {@link fromAsyncSink} to create\n * a regular sink that properly handles asynchronous operations.\n *\n * @param record The log record to process asynchronously.\n * @returns A promise that resolves when the record has been processed.\n * @since 1.0.0\n */\nexport type AsyncSink = (record: LogRecord) => Promise<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   * Enable non-blocking mode with optional buffer configuration.\n   * When enabled, log records are buffered and flushed in the background.\n   *\n   * @example Simple non-blocking mode\n   * ```typescript\n   * getStreamSink(stream, { nonBlocking: true });\n   * ```\n   *\n   * @example Custom buffer configuration\n   * ```typescript\n   * getStreamSink(stream, {\n   *   nonBlocking: {\n   *     bufferSize: 1000,\n   *     flushInterval: 50\n   *   }\n   * });\n   * ```\n   *\n   * @default `false`\n   * @since 1.0.0\n   */\n  nonBlocking?: boolean | {\n    /**\n     * Maximum number of records to buffer before flushing.\n     * @default `100`\n     */\n    bufferSize?: number;\n\n    /**\n     * Interval in milliseconds between automatic flushes.\n     * @default `100`\n     */\n    flushInterval?: number;\n  };\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\n  if (!options.nonBlocking) {\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\n  // Non-blocking mode implementation\n  const nonBlockingConfig = options.nonBlocking === true\n    ? {}\n    : options.nonBlocking;\n  const bufferSize = nonBlockingConfig.bufferSize ?? 100;\n  const flushInterval = nonBlockingConfig.flushInterval ?? 100;\n\n  const buffer: LogRecord[] = [];\n  let flushTimer: ReturnType<typeof setInterval> | null = null;\n  let disposed = false;\n  let activeFlush: Promise<void> | null = null;\n  const maxBufferSize = bufferSize * 2; // Overflow protection\n\n  async function flush(): Promise<void> {\n    if (buffer.length === 0) return;\n\n    const records = buffer.splice(0);\n    for (const record of records) {\n      try {\n        const bytes = encoder.encode(formatter(record));\n        await writer.ready;\n        await writer.write(bytes);\n      } catch {\n        // Silently ignore errors in non-blocking mode to avoid disrupting the application\n      }\n    }\n  }\n\n  function scheduleFlush(): void {\n    if (activeFlush) return;\n\n    activeFlush = flush().finally(() => {\n      activeFlush = null;\n    });\n  }\n\n  function startFlushTimer(): void {\n    if (flushTimer !== null || disposed) return;\n\n    flushTimer = setInterval(() => {\n      scheduleFlush();\n    }, flushInterval);\n  }\n\n  const nonBlockingSink: Sink & AsyncDisposable = (record: LogRecord) => {\n    if (disposed) return;\n\n    // Buffer overflow protection: drop oldest records if buffer is too large\n    if (buffer.length >= maxBufferSize) {\n      buffer.shift(); // Remove oldest record\n    }\n\n    buffer.push(record);\n\n    if (buffer.length >= bufferSize) {\n      scheduleFlush();\n    } else if (flushTimer === null) {\n      startFlushTimer();\n    }\n  };\n\n  nonBlockingSink[Symbol.asyncDispose] = async () => {\n    disposed = true;\n    if (flushTimer !== null) {\n      clearInterval(flushTimer);\n      flushTimer = null;\n    }\n    await flush();\n    try {\n      await writer.close();\n    } catch {\n      // Writer might already be closed or errored\n    }\n  };\n\n  return nonBlockingSink;\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   * Enable non-blocking mode with optional buffer configuration.\n   * When enabled, log records are buffered and flushed in the background.\n   *\n   * @example Simple non-blocking mode\n   * ```typescript\n   * getConsoleSink({ nonBlocking: true });\n   * ```\n   *\n   * @example Custom buffer configuration\n   * ```typescript\n   * getConsoleSink({\n   *   nonBlocking: {\n   *     bufferSize: 1000,\n   *     flushInterval: 50\n   *   }\n   * });\n   * ```\n   *\n   * @default `false`\n   * @since 1.0.0\n   */\n  nonBlocking?: boolean | {\n    /**\n     * Maximum number of records to buffer before flushing.\n     * @default `100`\n     */\n    bufferSize?: number;\n\n    /**\n     * Interval in milliseconds between automatic flushes.\n     * @default `100`\n     */\n    flushInterval?: number;\n  };\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. If `nonBlocking` is enabled,\n *          returns a sink that also implements {@link Disposable}.\n */\nexport function getConsoleSink(\n  options: ConsoleSinkOptions = {},\n): Sink | (Sink & Disposable) {\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\n  const baseSink = (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  if (!options.nonBlocking) {\n    return baseSink;\n  }\n\n  // Non-blocking mode implementation\n  const nonBlockingConfig = options.nonBlocking === true\n    ? {}\n    : options.nonBlocking;\n  const bufferSize = nonBlockingConfig.bufferSize ?? 100;\n  const flushInterval = nonBlockingConfig.flushInterval ?? 100;\n\n  const buffer: LogRecord[] = [];\n  let flushTimer: ReturnType<typeof setInterval> | null = null;\n  let disposed = false;\n  let flushScheduled = false;\n  const maxBufferSize = bufferSize * 2; // Overflow protection\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        baseSink(record);\n      } catch {\n        // Silently ignore errors in non-blocking mode to avoid disrupting the application\n      }\n    }\n  }\n\n  function scheduleFlush(): void {\n    if (flushScheduled) return;\n\n    flushScheduled = true;\n    setTimeout(() => {\n      flushScheduled = false;\n      flush();\n    }, 0);\n  }\n\n  function startFlushTimer(): void {\n    if (flushTimer !== null || disposed) return;\n\n    flushTimer = setInterval(() => {\n      flush();\n    }, flushInterval);\n  }\n\n  const nonBlockingSink: Sink & Disposable = (record: LogRecord) => {\n    if (disposed) return;\n\n    // Buffer overflow protection: drop oldest records if buffer is too large\n    if (buffer.length >= maxBufferSize) {\n      buffer.shift(); // Remove oldest record\n    }\n\n    buffer.push(record);\n\n    if (buffer.length >= bufferSize) {\n      scheduleFlush();\n    } else if (flushTimer === null) {\n      startFlushTimer();\n    }\n  };\n\n  nonBlockingSink[Symbol.dispose] = () => {\n    disposed = true;\n    if (flushTimer !== null) {\n      clearInterval(flushTimer);\n      flushTimer = null;\n    }\n    flush();\n  };\n\n  return nonBlockingSink;\n}\n\n/**\n * Converts an async sink into a regular sink with proper async handling.\n * The returned sink chains async operations to ensure proper ordering and\n * implements AsyncDisposable to wait for all pending operations on disposal.\n *\n * @example Create a sink that asynchronously posts to a webhook\n * ```typescript\n * const asyncSink: AsyncSink = async (record) => {\n *   await fetch(\"https://example.com/logs\", {\n *     method: \"POST\",\n *     body: JSON.stringify(record),\n *   });\n * };\n * const sink = fromAsyncSink(asyncSink);\n * ```\n *\n * @param asyncSink The async sink function to convert.\n * @returns A sink that properly handles async operations and disposal.\n * @since 1.0.0\n */\nexport function fromAsyncSink(asyncSink: AsyncSink): Sink & AsyncDisposable {\n  let lastPromise = Promise.resolve();\n  const sink: Sink & AsyncDisposable = (record: LogRecord) => {\n    lastPromise = lastPromise\n      .then(() => asyncSink(record))\n      .catch(() => {\n        // Errors are handled by the sink infrastructure\n      });\n  };\n  sink[Symbol.asyncDispose] = async () => {\n    await lastPromise;\n  };\n  return sink;\n}\n\n/**\n * Options for the {@link fingersCrossed} function.\n * @since 1.1.0\n */\nexport interface FingersCrossedOptions {\n  /**\n   * Minimum log level that triggers buffer flush.\n   * When a log record at or above this level is received, all buffered\n   * records are flushed to the wrapped sink.\n   * @default `\"error\"`\n   */\n  readonly triggerLevel?: LogLevel;\n\n  /**\n   * Maximum buffer size before oldest records are dropped.\n   * When the buffer exceeds this size, the oldest records are removed\n   * to prevent unbounded memory growth.\n   * @default `1000`\n   */\n  readonly maxBufferSize?: number;\n\n  /**\n   * Category isolation mode or custom matcher function.\n   *\n   * When `undefined` (default), all log records share a single buffer.\n   *\n   * When set to a mode string:\n   *\n   * - `\"descendant\"`: Flush child category buffers when parent triggers\n   * - `\"ancestor\"`: Flush parent category buffers when child triggers\n   * - `\"both\"`: Flush both parent and child category buffers\n   *\n   * When set to a function, it receives the trigger category and buffered\n   * category and should return true if the buffered category should be flushed.\n   *\n   * @default `undefined` (no isolation, single global buffer)\n   */\n  readonly isolateByCategory?:\n    | \"descendant\"\n    | \"ancestor\"\n    | \"both\"\n    | ((\n      triggerCategory: readonly string[],\n      bufferedCategory: readonly string[],\n    ) => boolean);\n}\n\n/**\n * Creates a sink that buffers log records until a trigger level is reached.\n * This pattern, known as \"fingers crossed\" logging, keeps detailed debug logs\n * in memory and only outputs them when an error or other significant event occurs.\n *\n * @example Basic usage with default settings\n * ```typescript\n * const sink = fingersCrossed(getConsoleSink());\n * // Debug and info logs are buffered\n * // When an error occurs, all buffered logs + the error are output\n * ```\n *\n * @example Custom trigger level and buffer size\n * ```typescript\n * const sink = fingersCrossed(getConsoleSink(), {\n *   triggerLevel: \"warning\",  // Trigger on warning or higher\n *   maxBufferSize: 500        // Keep last 500 records\n * });\n * ```\n *\n * @example Category isolation\n * ```typescript\n * const sink = fingersCrossed(getConsoleSink(), {\n *   isolateByCategory: \"descendant\"  // Separate buffers per category\n * });\n * // Error in [\"app\"] triggers flush of [\"app\"] and [\"app\", \"module\"] buffers\n * // But not [\"other\"] buffer\n * ```\n *\n * @param sink The sink to wrap. Buffered records are sent to this sink when\n *             triggered.\n * @param options Configuration options for the fingers crossed behavior.\n * @returns A sink that buffers records until the trigger level is reached.\n * @since 1.1.0\n */\nexport function fingersCrossed(\n  sink: Sink,\n  options: FingersCrossedOptions = {},\n): Sink {\n  const triggerLevel = options.triggerLevel ?? \"error\";\n  const maxBufferSize = Math.max(0, options.maxBufferSize ?? 1000);\n  const isolateByCategory = options.isolateByCategory;\n\n  // Validate trigger level early\n  try {\n    compareLogLevel(\"trace\", triggerLevel); // Test with any valid level\n  } catch (error) {\n    throw new TypeError(\n      `Invalid triggerLevel: ${JSON.stringify(triggerLevel)}. ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n    );\n  }\n\n  // Helper functions for category matching\n  function isDescendant(\n    parent: readonly string[],\n    child: readonly string[],\n  ): boolean {\n    if (parent.length === 0 || child.length === 0) return false; // Empty categories are isolated\n    if (parent.length > child.length) return false;\n    return parent.every((p, i) => p === child[i]);\n  }\n\n  function isAncestor(\n    child: readonly string[],\n    parent: readonly string[],\n  ): boolean {\n    if (child.length === 0 || parent.length === 0) return false; // Empty categories are isolated\n    if (child.length < parent.length) return false;\n    return parent.every((p, i) => p === child[i]);\n  }\n\n  // Determine matcher function based on isolation mode\n  let shouldFlushBuffer:\n    | ((\n      triggerCategory: readonly string[],\n      bufferedCategory: readonly string[],\n    ) => boolean)\n    | null = null;\n\n  if (isolateByCategory) {\n    if (typeof isolateByCategory === \"function\") {\n      shouldFlushBuffer = isolateByCategory;\n    } else {\n      switch (isolateByCategory) {\n        case \"descendant\":\n          shouldFlushBuffer = (trigger, buffered) =>\n            isDescendant(trigger, buffered);\n          break;\n        case \"ancestor\":\n          shouldFlushBuffer = (trigger, buffered) =>\n            isAncestor(trigger, buffered);\n          break;\n        case \"both\":\n          shouldFlushBuffer = (trigger, buffered) =>\n            isDescendant(trigger, buffered) || isAncestor(trigger, buffered);\n          break;\n      }\n    }\n  }\n\n  // Helper functions for category serialization\n  function getCategoryKey(category: readonly string[]): string {\n    return JSON.stringify(category);\n  }\n\n  function parseCategoryKey(key: string): string[] {\n    return JSON.parse(key);\n  }\n\n  // Buffer management\n  if (!isolateByCategory) {\n    // Single global buffer\n    const buffer: LogRecord[] = [];\n    let triggered = false;\n\n    return (record: LogRecord) => {\n      if (triggered) {\n        // Already triggered, pass through directly\n        sink(record);\n        return;\n      }\n\n      // Check if this record triggers flush\n      if (compareLogLevel(record.level, triggerLevel) >= 0) {\n        triggered = true;\n\n        // Flush buffer\n        for (const bufferedRecord of buffer) {\n          sink(bufferedRecord);\n        }\n        buffer.length = 0;\n\n        // Send trigger record\n        sink(record);\n      } else {\n        // Buffer the record\n        buffer.push(record);\n\n        // Enforce max buffer size\n        while (buffer.length > maxBufferSize) {\n          buffer.shift();\n        }\n      }\n    };\n  } else {\n    // Category-isolated buffers\n    const buffers = new Map<string, LogRecord[]>();\n    const triggered = new Set<string>();\n\n    return (record: LogRecord) => {\n      const categoryKey = getCategoryKey(record.category);\n\n      // Check if this category is already triggered\n      if (triggered.has(categoryKey)) {\n        sink(record);\n        return;\n      }\n\n      // Check if this record triggers flush\n      if (compareLogLevel(record.level, triggerLevel) >= 0) {\n        // Find all buffers that should be flushed\n        const keysToFlush = new Set<string>();\n\n        for (const [bufferedKey] of buffers) {\n          if (bufferedKey === categoryKey) {\n            keysToFlush.add(bufferedKey);\n          } else if (shouldFlushBuffer) {\n            const bufferedCategory = parseCategoryKey(bufferedKey);\n            try {\n              if (shouldFlushBuffer(record.category, bufferedCategory)) {\n                keysToFlush.add(bufferedKey);\n              }\n            } catch {\n              // Ignore errors from custom matcher\n            }\n          }\n        }\n\n        // Flush matching buffers\n        const allRecordsToFlush: LogRecord[] = [];\n        for (const key of keysToFlush) {\n          const buffer = buffers.get(key);\n          if (buffer) {\n            allRecordsToFlush.push(...buffer);\n            buffers.delete(key);\n            triggered.add(key);\n          }\n        }\n\n        // Sort by timestamp to maintain chronological order\n        allRecordsToFlush.sort((a, b) => a.timestamp - b.timestamp);\n\n        // Flush all records\n        for (const bufferedRecord of allRecordsToFlush) {\n          sink(bufferedRecord);\n        }\n\n        // Mark trigger category as triggered and send trigger record\n        triggered.add(categoryKey);\n        sink(record);\n      } else {\n        // Buffer the record\n        let buffer = buffers.get(categoryKey);\n        if (!buffer) {\n          buffer = [];\n          buffers.set(categoryKey, buffer);\n        }\n\n        buffer.push(record);\n\n        // Enforce max buffer size per category\n        while (buffer.length > maxBufferSize) {\n          buffer.shift();\n        }\n      }\n    };\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"sink.js","names":["sink: Sink","filter: FilterLike","record: LogRecord","stream: WritableStream","options: StreamSinkOptions","sink: Sink & AsyncDisposable","buffer: LogRecord[]","flushTimer: ReturnType<typeof setInterval> | null","activeFlush: Promise<void> | null","nonBlockingSink: Sink & AsyncDisposable","options: ConsoleSinkOptions","levelMap: Record<LogLevel, ConsoleMethod>","nonBlockingSink: Sink & Disposable","asyncSink: AsyncSink","options: FingersCrossedOptions","parent: readonly string[]","child: readonly string[]","shouldFlushBuffer:\n    | ((\n      triggerCategory: readonly string[],\n      bufferedCategory: readonly string[],\n    ) => boolean)\n    | null","category: readonly string[]","key: string","properties: Record<string, unknown>","contextValues: Record<string, unknown>","allRecordsToFlush: LogRecord[]"],"sources":["../src/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 { compareLogLevel, 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 * An async sink is a function that accepts a log record and asynchronously\n * processes it. This type is used with {@link fromAsyncSink} to create\n * a regular sink that properly handles asynchronous operations.\n *\n * @param record The log record to process asynchronously.\n * @returns A promise that resolves when the record has been processed.\n * @since 1.0.0\n */\nexport type AsyncSink = (record: LogRecord) => Promise<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   * Enable non-blocking mode with optional buffer configuration.\n   * When enabled, log records are buffered and flushed in the background.\n   *\n   * @example Simple non-blocking mode\n   * ```typescript\n   * getStreamSink(stream, { nonBlocking: true });\n   * ```\n   *\n   * @example Custom buffer configuration\n   * ```typescript\n   * getStreamSink(stream, {\n   *   nonBlocking: {\n   *     bufferSize: 1000,\n   *     flushInterval: 50\n   *   }\n   * });\n   * ```\n   *\n   * @default `false`\n   * @since 1.0.0\n   */\n  nonBlocking?: boolean | {\n    /**\n     * Maximum number of records to buffer before flushing.\n     * @default `100`\n     */\n    bufferSize?: number;\n\n    /**\n     * Interval in milliseconds between automatic flushes.\n     * @default `100`\n     */\n    flushInterval?: number;\n  };\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\n  if (!options.nonBlocking) {\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\n  // Non-blocking mode implementation\n  const nonBlockingConfig = options.nonBlocking === true\n    ? {}\n    : options.nonBlocking;\n  const bufferSize = nonBlockingConfig.bufferSize ?? 100;\n  const flushInterval = nonBlockingConfig.flushInterval ?? 100;\n\n  const buffer: LogRecord[] = [];\n  let flushTimer: ReturnType<typeof setInterval> | null = null;\n  let disposed = false;\n  let activeFlush: Promise<void> | null = null;\n  const maxBufferSize = bufferSize * 2; // Overflow protection\n\n  async function flush(): Promise<void> {\n    if (buffer.length === 0) return;\n\n    const records = buffer.splice(0);\n    for (const record of records) {\n      try {\n        const bytes = encoder.encode(formatter(record));\n        await writer.ready;\n        await writer.write(bytes);\n      } catch {\n        // Silently ignore errors in non-blocking mode to avoid disrupting the application\n      }\n    }\n  }\n\n  function scheduleFlush(): void {\n    if (activeFlush) return;\n\n    activeFlush = flush().finally(() => {\n      activeFlush = null;\n    });\n  }\n\n  function startFlushTimer(): void {\n    if (flushTimer !== null || disposed) return;\n\n    flushTimer = setInterval(() => {\n      scheduleFlush();\n    }, flushInterval);\n  }\n\n  const nonBlockingSink: Sink & AsyncDisposable = (record: LogRecord) => {\n    if (disposed) return;\n\n    // Buffer overflow protection: drop oldest records if buffer is too large\n    if (buffer.length >= maxBufferSize) {\n      buffer.shift(); // Remove oldest record\n    }\n\n    buffer.push(record);\n\n    if (buffer.length >= bufferSize) {\n      scheduleFlush();\n    } else if (flushTimer === null) {\n      startFlushTimer();\n    }\n  };\n\n  nonBlockingSink[Symbol.asyncDispose] = async () => {\n    disposed = true;\n    if (flushTimer !== null) {\n      clearInterval(flushTimer);\n      flushTimer = null;\n    }\n    await flush();\n    try {\n      await writer.close();\n    } catch {\n      // Writer might already be closed or errored\n    }\n  };\n\n  return nonBlockingSink;\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   * Enable non-blocking mode with optional buffer configuration.\n   * When enabled, log records are buffered and flushed in the background.\n   *\n   * @example Simple non-blocking mode\n   * ```typescript\n   * getConsoleSink({ nonBlocking: true });\n   * ```\n   *\n   * @example Custom buffer configuration\n   * ```typescript\n   * getConsoleSink({\n   *   nonBlocking: {\n   *     bufferSize: 1000,\n   *     flushInterval: 50\n   *   }\n   * });\n   * ```\n   *\n   * @default `false`\n   * @since 1.0.0\n   */\n  nonBlocking?: boolean | {\n    /**\n     * Maximum number of records to buffer before flushing.\n     * @default `100`\n     */\n    bufferSize?: number;\n\n    /**\n     * Interval in milliseconds between automatic flushes.\n     * @default `100`\n     */\n    flushInterval?: number;\n  };\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. If `nonBlocking` is enabled,\n *          returns a sink that also implements {@link Disposable}.\n */\nexport function getConsoleSink(\n  options: ConsoleSinkOptions = {},\n): Sink | (Sink & Disposable) {\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\n  const baseSink = (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  if (!options.nonBlocking) {\n    return baseSink;\n  }\n\n  // Non-blocking mode implementation\n  const nonBlockingConfig = options.nonBlocking === true\n    ? {}\n    : options.nonBlocking;\n  const bufferSize = nonBlockingConfig.bufferSize ?? 100;\n  const flushInterval = nonBlockingConfig.flushInterval ?? 100;\n\n  const buffer: LogRecord[] = [];\n  let flushTimer: ReturnType<typeof setInterval> | null = null;\n  let disposed = false;\n  let flushScheduled = false;\n  const maxBufferSize = bufferSize * 2; // Overflow protection\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        baseSink(record);\n      } catch {\n        // Silently ignore errors in non-blocking mode to avoid disrupting the application\n      }\n    }\n  }\n\n  function scheduleFlush(): void {\n    if (flushScheduled) return;\n\n    flushScheduled = true;\n    setTimeout(() => {\n      flushScheduled = false;\n      flush();\n    }, 0);\n  }\n\n  function startFlushTimer(): void {\n    if (flushTimer !== null || disposed) return;\n\n    flushTimer = setInterval(() => {\n      flush();\n    }, flushInterval);\n  }\n\n  const nonBlockingSink: Sink & Disposable = (record: LogRecord) => {\n    if (disposed) return;\n\n    // Buffer overflow protection: drop oldest records if buffer is too large\n    if (buffer.length >= maxBufferSize) {\n      buffer.shift(); // Remove oldest record\n    }\n\n    buffer.push(record);\n\n    if (buffer.length >= bufferSize) {\n      scheduleFlush();\n    } else if (flushTimer === null) {\n      startFlushTimer();\n    }\n  };\n\n  nonBlockingSink[Symbol.dispose] = () => {\n    disposed = true;\n    if (flushTimer !== null) {\n      clearInterval(flushTimer);\n      flushTimer = null;\n    }\n    flush();\n  };\n\n  return nonBlockingSink;\n}\n\n/**\n * Converts an async sink into a regular sink with proper async handling.\n * The returned sink chains async operations to ensure proper ordering and\n * implements AsyncDisposable to wait for all pending operations on disposal.\n *\n * @example Create a sink that asynchronously posts to a webhook\n * ```typescript\n * const asyncSink: AsyncSink = async (record) => {\n *   await fetch(\"https://example.com/logs\", {\n *     method: \"POST\",\n *     body: JSON.stringify(record),\n *   });\n * };\n * const sink = fromAsyncSink(asyncSink);\n * ```\n *\n * @param asyncSink The async sink function to convert.\n * @returns A sink that properly handles async operations and disposal.\n * @since 1.0.0\n */\nexport function fromAsyncSink(asyncSink: AsyncSink): Sink & AsyncDisposable {\n  let lastPromise = Promise.resolve();\n  const sink: Sink & AsyncDisposable = (record: LogRecord) => {\n    lastPromise = lastPromise\n      .then(() => asyncSink(record))\n      .catch(() => {\n        // Errors are handled by the sink infrastructure\n      });\n  };\n  sink[Symbol.asyncDispose] = async () => {\n    await lastPromise;\n  };\n  return sink;\n}\n\n/**\n * Options for the {@link fingersCrossed} function.\n * @since 1.1.0\n */\nexport interface FingersCrossedOptions {\n  /**\n   * Minimum log level that triggers buffer flush.\n   * When a log record at or above this level is received, all buffered\n   * records are flushed to the wrapped sink.\n   * @default `\"error\"`\n   */\n  readonly triggerLevel?: LogLevel;\n\n  /**\n   * Maximum buffer size before oldest records are dropped.\n   * When the buffer exceeds this size, the oldest records are removed\n   * to prevent unbounded memory growth.\n   * @default `1000`\n   */\n  readonly maxBufferSize?: number;\n\n  /**\n   * Category isolation mode or custom matcher function.\n   *\n   * When `undefined` (default), all log records share a single buffer.\n   *\n   * When set to a mode string:\n   *\n   * - `\"descendant\"`: Flush child category buffers when parent triggers\n   * - `\"ancestor\"`: Flush parent category buffers when child triggers\n   * - `\"both\"`: Flush both parent and child category buffers\n   *\n   * When set to a function, it receives the trigger category and buffered\n   * category and should return true if the buffered category should be flushed.\n   *\n   * @default `undefined` (no isolation, single global buffer)\n   */\n  readonly isolateByCategory?:\n    | \"descendant\"\n    | \"ancestor\"\n    | \"both\"\n    | ((\n      triggerCategory: readonly string[],\n      bufferedCategory: readonly string[],\n    ) => boolean);\n\n  /**\n   * Enable context-based buffer isolation.\n   * When enabled, buffers are isolated based on specified context keys.\n   * This is useful for scenarios like HTTP request tracing where logs\n   * should be isolated per request.\n   *\n   * @example\n   * ```typescript\n   * fingersCrossed(sink, {\n   *   isolateByContext: { keys: ['requestId'] }\n   * })\n   * ```\n   *\n   * @example Combined with category isolation\n   * ```typescript\n   * fingersCrossed(sink, {\n   *   isolateByCategory: 'descendant',\n   *   isolateByContext: { keys: ['requestId', 'sessionId'] }\n   * })\n   * ```\n   *\n   * @default `undefined` (no context isolation)\n   * @since 1.2.0\n   */\n  readonly isolateByContext?: {\n    /**\n     * Context keys to use for isolation.\n     * Buffers will be separate for different combinations of these context values.\n     */\n    readonly keys: readonly string[];\n  };\n}\n\n/**\n * Creates a sink that buffers log records until a trigger level is reached.\n * This pattern, known as \"fingers crossed\" logging, keeps detailed debug logs\n * in memory and only outputs them when an error or other significant event occurs.\n *\n * @example Basic usage with default settings\n * ```typescript\n * const sink = fingersCrossed(getConsoleSink());\n * // Debug and info logs are buffered\n * // When an error occurs, all buffered logs + the error are output\n * ```\n *\n * @example Custom trigger level and buffer size\n * ```typescript\n * const sink = fingersCrossed(getConsoleSink(), {\n *   triggerLevel: \"warning\",  // Trigger on warning or higher\n *   maxBufferSize: 500        // Keep last 500 records\n * });\n * ```\n *\n * @example Category isolation\n * ```typescript\n * const sink = fingersCrossed(getConsoleSink(), {\n *   isolateByCategory: \"descendant\"  // Separate buffers per category\n * });\n * // Error in [\"app\"] triggers flush of [\"app\"] and [\"app\", \"module\"] buffers\n * // But not [\"other\"] buffer\n * ```\n *\n * @param sink The sink to wrap. Buffered records are sent to this sink when\n *             triggered.\n * @param options Configuration options for the fingers crossed behavior.\n * @returns A sink that buffers records until the trigger level is reached.\n * @since 1.1.0\n */\nexport function fingersCrossed(\n  sink: Sink,\n  options: FingersCrossedOptions = {},\n): Sink {\n  const triggerLevel = options.triggerLevel ?? \"error\";\n  const maxBufferSize = Math.max(0, options.maxBufferSize ?? 1000);\n  const isolateByCategory = options.isolateByCategory;\n  const isolateByContext = options.isolateByContext;\n\n  // Validate trigger level early\n  try {\n    compareLogLevel(\"trace\", triggerLevel); // Test with any valid level\n  } catch (error) {\n    throw new TypeError(\n      `Invalid triggerLevel: ${JSON.stringify(triggerLevel)}. ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n    );\n  }\n\n  // Helper functions for category matching\n  function isDescendant(\n    parent: readonly string[],\n    child: readonly string[],\n  ): boolean {\n    if (parent.length === 0 || child.length === 0) return false; // Empty categories are isolated\n    if (parent.length > child.length) return false;\n    return parent.every((p, i) => p === child[i]);\n  }\n\n  function isAncestor(\n    child: readonly string[],\n    parent: readonly string[],\n  ): boolean {\n    if (child.length === 0 || parent.length === 0) return false; // Empty categories are isolated\n    if (child.length < parent.length) return false;\n    return parent.every((p, i) => p === child[i]);\n  }\n\n  // Determine matcher function based on isolation mode\n  let shouldFlushBuffer:\n    | ((\n      triggerCategory: readonly string[],\n      bufferedCategory: readonly string[],\n    ) => boolean)\n    | null = null;\n\n  if (isolateByCategory) {\n    if (typeof isolateByCategory === \"function\") {\n      shouldFlushBuffer = isolateByCategory;\n    } else {\n      switch (isolateByCategory) {\n        case \"descendant\":\n          shouldFlushBuffer = (trigger, buffered) =>\n            isDescendant(trigger, buffered);\n          break;\n        case \"ancestor\":\n          shouldFlushBuffer = (trigger, buffered) =>\n            isAncestor(trigger, buffered);\n          break;\n        case \"both\":\n          shouldFlushBuffer = (trigger, buffered) =>\n            isDescendant(trigger, buffered) || isAncestor(trigger, buffered);\n          break;\n      }\n    }\n  }\n\n  // Helper functions for category serialization\n  function getCategoryKey(category: readonly string[]): string {\n    return JSON.stringify(category);\n  }\n\n  function parseCategoryKey(key: string): string[] {\n    return JSON.parse(key);\n  }\n\n  // Helper function to extract context values from properties\n  function getContextKey(properties: Record<string, unknown>): string {\n    if (!isolateByContext || isolateByContext.keys.length === 0) {\n      return \"\";\n    }\n    const contextValues: Record<string, unknown> = {};\n    for (const key of isolateByContext.keys) {\n      if (key in properties) {\n        contextValues[key] = properties[key];\n      }\n    }\n    return JSON.stringify(contextValues);\n  }\n\n  // Helper function to generate buffer key\n  function getBufferKey(\n    category: readonly string[],\n    properties: Record<string, unknown>,\n  ): string {\n    const categoryKey = getCategoryKey(category);\n    if (!isolateByContext) {\n      return categoryKey;\n    }\n    const contextKey = getContextKey(properties);\n    return `${categoryKey}:${contextKey}`;\n  }\n\n  // Helper function to parse buffer key\n  function parseBufferKey(key: string): {\n    category: string[];\n    context: string;\n  } {\n    if (!isolateByContext) {\n      return { category: parseCategoryKey(key), context: \"\" };\n    }\n    // Find the separator between category and context\n    // The category part is JSON-encoded, so we need to find where it ends\n    // We look for \"]:\" which indicates end of category array and start of context\n    const separatorIndex = key.indexOf(\"]:\");\n    if (separatorIndex === -1) {\n      // No context part, entire key is category\n      return { category: parseCategoryKey(key), context: \"\" };\n    }\n    const categoryPart = key.substring(0, separatorIndex + 1); // Include the ]\n    const contextPart = key.substring(separatorIndex + 2); // Skip ]:\n    return { category: parseCategoryKey(categoryPart), context: contextPart };\n  }\n\n  // Buffer management\n  if (!isolateByCategory && !isolateByContext) {\n    // Single global buffer\n    const buffer: LogRecord[] = [];\n    let triggered = false;\n\n    return (record: LogRecord) => {\n      if (triggered) {\n        // Already triggered, pass through directly\n        sink(record);\n        return;\n      }\n\n      // Check if this record triggers flush\n      if (compareLogLevel(record.level, triggerLevel) >= 0) {\n        triggered = true;\n\n        // Flush buffer\n        for (const bufferedRecord of buffer) {\n          sink(bufferedRecord);\n        }\n        buffer.length = 0;\n\n        // Send trigger record\n        sink(record);\n      } else {\n        // Buffer the record\n        buffer.push(record);\n\n        // Enforce max buffer size\n        while (buffer.length > maxBufferSize) {\n          buffer.shift();\n        }\n      }\n    };\n  } else {\n    // Category and/or context-isolated buffers\n    const buffers = new Map<string, LogRecord[]>();\n    const triggered = new Set<string>();\n\n    return (record: LogRecord) => {\n      const bufferKey = getBufferKey(record.category, record.properties);\n\n      // Check if this buffer is already triggered\n      if (triggered.has(bufferKey)) {\n        sink(record);\n        return;\n      }\n\n      // Check if this record triggers flush\n      if (compareLogLevel(record.level, triggerLevel) >= 0) {\n        // Find all buffers that should be flushed\n        const keysToFlush = new Set<string>();\n\n        for (const [bufferedKey] of buffers) {\n          if (bufferedKey === bufferKey) {\n            keysToFlush.add(bufferedKey);\n          } else {\n            const { category: bufferedCategory, context: bufferedContext } =\n              parseBufferKey(bufferedKey);\n            const { context: triggerContext } = parseBufferKey(bufferKey);\n\n            // Check context match\n            let contextMatches = true;\n            if (isolateByContext) {\n              contextMatches = bufferedContext === triggerContext;\n            }\n\n            // Check category match\n            let categoryMatches = false;\n            if (!isolateByCategory) {\n              // No category isolation, so all categories match if context matches\n              categoryMatches = contextMatches;\n            } else if (shouldFlushBuffer) {\n              try {\n                categoryMatches = shouldFlushBuffer(\n                  record.category,\n                  bufferedCategory,\n                );\n              } catch {\n                // Ignore errors from custom matcher\n              }\n            } else {\n              // Same category only\n              categoryMatches = getCategoryKey(record.category) ===\n                getCategoryKey(bufferedCategory);\n            }\n\n            // Both must match for the buffer to be flushed\n            if (contextMatches && categoryMatches) {\n              keysToFlush.add(bufferedKey);\n            }\n          }\n        }\n\n        // Flush matching buffers\n        const allRecordsToFlush: LogRecord[] = [];\n        for (const key of keysToFlush) {\n          const buffer = buffers.get(key);\n          if (buffer) {\n            allRecordsToFlush.push(...buffer);\n            buffers.delete(key);\n            triggered.add(key);\n          }\n        }\n\n        // Sort by timestamp to maintain chronological order\n        allRecordsToFlush.sort((a, b) => a.timestamp - b.timestamp);\n\n        // Flush all records\n        for (const bufferedRecord of allRecordsToFlush) {\n          sink(bufferedRecord);\n        }\n\n        // Mark trigger buffer as triggered and send trigger record\n        triggered.add(bufferKey);\n        sink(record);\n      } else {\n        // Buffer the record\n        let buffer = buffers.get(bufferKey);\n        if (!buffer) {\n          buffer = [];\n          buffers.set(bufferKey, buffer);\n        }\n\n        buffer.push(record);\n\n        // Enforce max buffer size per buffer\n        while (buffer.length > maxBufferSize) {\n          buffer.shift();\n        }\n      }\n    };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA8CA,SAAgB,WAAWA,MAAYC,QAA0B;CAC/D,MAAM,aAAa,SAAS,OAAO;AACnC,QAAO,CAACC,WAAsB;AAC5B,MAAI,WAAW,OAAO,CAAE,MAAK,OAAO;CACrC;AACF;;;;;;;;;;;;;;;;;;;;;;;;;AA6ED,SAAgB,cACdC,QACAC,UAA6B,CAAE,GACP;CACxB,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,UAAU,QAAQ,WAAW,IAAI;CACvC,MAAM,SAAS,OAAO,WAAW;AAEjC,MAAK,QAAQ,aAAa;EACxB,IAAI,cAAc,QAAQ,SAAS;EACnC,MAAMC,OAA+B,CAACH,WAAsB;GAC1D,MAAM,QAAQ,QAAQ,OAAO,UAAU,OAAO,CAAC;AAC/C,iBAAc,YACX,KAAK,MAAM,OAAO,MAAM,CACxB,KAAK,MAAM,OAAO,MAAM,MAAM,CAAC;EACnC;AACD,OAAK,OAAO,gBAAgB,YAAY;AACtC,SAAM;AACN,SAAM,OAAO,OAAO;EACrB;AACD,SAAO;CACR;CAGD,MAAM,oBAAoB,QAAQ,gBAAgB,OAC9C,CAAE,IACF,QAAQ;CACZ,MAAM,aAAa,kBAAkB,cAAc;CACnD,MAAM,gBAAgB,kBAAkB,iBAAiB;CAEzD,MAAMI,SAAsB,CAAE;CAC9B,IAAIC,aAAoD;CACxD,IAAI,WAAW;CACf,IAAIC,cAAoC;CACxC,MAAM,gBAAgB,aAAa;CAEnC,eAAe,QAAuB;AACpC,MAAI,OAAO,WAAW,EAAG;EAEzB,MAAM,UAAU,OAAO,OAAO,EAAE;AAChC,OAAK,MAAM,UAAU,QACnB,KAAI;GACF,MAAM,QAAQ,QAAQ,OAAO,UAAU,OAAO,CAAC;AAC/C,SAAM,OAAO;AACb,SAAM,OAAO,MAAM,MAAM;EAC1B,QAAO,CAEP;CAEJ;CAED,SAAS,gBAAsB;AAC7B,MAAI,YAAa;AAEjB,gBAAc,OAAO,CAAC,QAAQ,MAAM;AAClC,iBAAc;EACf,EAAC;CACH;CAED,SAAS,kBAAwB;AAC/B,MAAI,eAAe,QAAQ,SAAU;AAErC,eAAa,YAAY,MAAM;AAC7B,kBAAe;EAChB,GAAE,cAAc;CAClB;CAED,MAAMC,kBAA0C,CAACP,WAAsB;AACrE,MAAI,SAAU;AAGd,MAAI,OAAO,UAAU,cACnB,QAAO,OAAO;AAGhB,SAAO,KAAK,OAAO;AAEnB,MAAI,OAAO,UAAU,WACnB,gBAAe;WACN,eAAe,KACxB,kBAAiB;CAEpB;AAED,iBAAgB,OAAO,gBAAgB,YAAY;AACjD,aAAW;AACX,MAAI,eAAe,MAAM;AACvB,iBAAc,WAAW;AACzB,gBAAa;EACd;AACD,QAAM,OAAO;AACb,MAAI;AACF,SAAM,OAAO,OAAO;EACrB,QAAO,CAEP;CACF;AAED,QAAO;AACR;;;;;;;;AAgFD,SAAgB,eACdQ,UAA8B,CAAE,GACJ;CAC5B,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;CAE9C,MAAM,WAAW,CAACT,WAAsB;EACtC,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;AAED,MAAK,QAAQ,YACX,QAAO;CAIT,MAAM,oBAAoB,QAAQ,gBAAgB,OAC9C,CAAE,IACF,QAAQ;CACZ,MAAM,aAAa,kBAAkB,cAAc;CACnD,MAAM,gBAAgB,kBAAkB,iBAAiB;CAEzD,MAAMI,SAAsB,CAAE;CAC9B,IAAIC,aAAoD;CACxD,IAAI,WAAW;CACf,IAAI,iBAAiB;CACrB,MAAM,gBAAgB,aAAa;CAEnC,SAAS,QAAc;AACrB,MAAI,OAAO,WAAW,EAAG;EAEzB,MAAM,UAAU,OAAO,OAAO,EAAE;AAChC,OAAK,MAAM,UAAU,QACnB,KAAI;AACF,YAAS,OAAO;EACjB,QAAO,CAEP;CAEJ;CAED,SAAS,gBAAsB;AAC7B,MAAI,eAAgB;AAEpB,mBAAiB;AACjB,aAAW,MAAM;AACf,oBAAiB;AACjB,UAAO;EACR,GAAE,EAAE;CACN;CAED,SAAS,kBAAwB;AAC/B,MAAI,eAAe,QAAQ,SAAU;AAErC,eAAa,YAAY,MAAM;AAC7B,UAAO;EACR,GAAE,cAAc;CAClB;CAED,MAAMK,kBAAqC,CAACV,WAAsB;AAChE,MAAI,SAAU;AAGd,MAAI,OAAO,UAAU,cACnB,QAAO,OAAO;AAGhB,SAAO,KAAK,OAAO;AAEnB,MAAI,OAAO,UAAU,WACnB,gBAAe;WACN,eAAe,KACxB,kBAAiB;CAEpB;AAED,iBAAgB,OAAO,WAAW,MAAM;AACtC,aAAW;AACX,MAAI,eAAe,MAAM;AACvB,iBAAc,WAAW;AACzB,gBAAa;EACd;AACD,SAAO;CACR;AAED,QAAO;AACR;;;;;;;;;;;;;;;;;;;;;AAsBD,SAAgB,cAAcW,WAA8C;CAC1E,IAAI,cAAc,QAAQ,SAAS;CACnC,MAAMR,OAA+B,CAACH,WAAsB;AAC1D,gBAAc,YACX,KAAK,MAAM,UAAU,OAAO,CAAC,CAC7B,MAAM,MAAM,CAEZ,EAAC;CACL;AACD,MAAK,OAAO,gBAAgB,YAAY;AACtC,QAAM;CACP;AACD,QAAO;AACR;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoHD,SAAgB,eACdF,MACAc,UAAiC,CAAE,GAC7B;CACN,MAAM,eAAe,QAAQ,gBAAgB;CAC7C,MAAM,gBAAgB,KAAK,IAAI,GAAG,QAAQ,iBAAiB,IAAK;CAChE,MAAM,oBAAoB,QAAQ;CAClC,MAAM,mBAAmB,QAAQ;AAGjC,KAAI;AACF,kBAAgB,SAAS,aAAa;CACvC,SAAQ,OAAO;AACd,QAAM,IAAI,WACP,wBAAwB,KAAK,UAAU,aAAa,CAAC,IACpD,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,CACvD;CAEJ;CAGD,SAAS,aACPC,QACAC,OACS;AACT,MAAI,OAAO,WAAW,KAAK,MAAM,WAAW,EAAG,QAAO;AACtD,MAAI,OAAO,SAAS,MAAM,OAAQ,QAAO;AACzC,SAAO,OAAO,MAAM,CAAC,GAAG,MAAM,MAAM,MAAM,GAAG;CAC9C;CAED,SAAS,WACPA,OACAD,QACS;AACT,MAAI,MAAM,WAAW,KAAK,OAAO,WAAW,EAAG,QAAO;AACtD,MAAI,MAAM,SAAS,OAAO,OAAQ,QAAO;AACzC,SAAO,OAAO,MAAM,CAAC,GAAG,MAAM,MAAM,MAAM,GAAG;CAC9C;CAGD,IAAIE,oBAKO;AAEX,KAAI,kBACF,YAAW,sBAAsB,WAC/B,qBAAoB;KAEpB,SAAQ,mBAAR;EACE,KAAK;AACH,uBAAoB,CAAC,SAAS,aAC5B,aAAa,SAAS,SAAS;AACjC;EACF,KAAK;AACH,uBAAoB,CAAC,SAAS,aAC5B,WAAW,SAAS,SAAS;AAC/B;EACF,KAAK;AACH,uBAAoB,CAAC,SAAS,aAC5B,aAAa,SAAS,SAAS,IAAI,WAAW,SAAS,SAAS;AAClE;CACH;CAKL,SAAS,eAAeC,UAAqC;AAC3D,SAAO,KAAK,UAAU,SAAS;CAChC;CAED,SAAS,iBAAiBC,KAAuB;AAC/C,SAAO,KAAK,MAAM,IAAI;CACvB;CAGD,SAAS,cAAcC,YAA6C;AAClE,OAAK,oBAAoB,iBAAiB,KAAK,WAAW,EACxD,QAAO;EAET,MAAMC,gBAAyC,CAAE;AACjD,OAAK,MAAM,OAAO,iBAAiB,KACjC,KAAI,OAAO,WACT,eAAc,OAAO,WAAW;AAGpC,SAAO,KAAK,UAAU,cAAc;CACrC;CAGD,SAAS,aACPH,UACAE,YACQ;EACR,MAAM,cAAc,eAAe,SAAS;AAC5C,OAAK,iBACH,QAAO;EAET,MAAM,aAAa,cAAc,WAAW;AAC5C,UAAQ,EAAE,YAAY,GAAG,WAAW;CACrC;CAGD,SAAS,eAAeD,KAGtB;AACA,OAAK,iBACH,QAAO;GAAE,UAAU,iBAAiB,IAAI;GAAE,SAAS;EAAI;EAKzD,MAAM,iBAAiB,IAAI,QAAQ,KAAK;AACxC,MAAI,mBAAmB,GAErB,QAAO;GAAE,UAAU,iBAAiB,IAAI;GAAE,SAAS;EAAI;EAEzD,MAAM,eAAe,IAAI,UAAU,GAAG,iBAAiB,EAAE;EACzD,MAAM,cAAc,IAAI,UAAU,iBAAiB,EAAE;AACrD,SAAO;GAAE,UAAU,iBAAiB,aAAa;GAAE,SAAS;EAAa;CAC1E;AAGD,MAAK,sBAAsB,kBAAkB;EAE3C,MAAMb,SAAsB,CAAE;EAC9B,IAAI,YAAY;AAEhB,SAAO,CAACJ,WAAsB;AAC5B,OAAI,WAAW;AAEb,SAAK,OAAO;AACZ;GACD;AAGD,OAAI,gBAAgB,OAAO,OAAO,aAAa,IAAI,GAAG;AACpD,gBAAY;AAGZ,SAAK,MAAM,kBAAkB,OAC3B,MAAK,eAAe;AAEtB,WAAO,SAAS;AAGhB,SAAK,OAAO;GACb,OAAM;AAEL,WAAO,KAAK,OAAO;AAGnB,WAAO,OAAO,SAAS,cACrB,QAAO,OAAO;GAEjB;EACF;CACF,OAAM;EAEL,MAAM,0BAAU,IAAI;EACpB,MAAM,4BAAY,IAAI;AAEtB,SAAO,CAACA,WAAsB;GAC5B,MAAM,YAAY,aAAa,OAAO,UAAU,OAAO,WAAW;AAGlE,OAAI,UAAU,IAAI,UAAU,EAAE;AAC5B,SAAK,OAAO;AACZ;GACD;AAGD,OAAI,gBAAgB,OAAO,OAAO,aAAa,IAAI,GAAG;IAEpD,MAAM,8BAAc,IAAI;AAExB,SAAK,MAAM,CAAC,YAAY,IAAI,QAC1B,KAAI,gBAAgB,UAClB,aAAY,IAAI,YAAY;SACvB;KACL,MAAM,EAAE,UAAU,kBAAkB,SAAS,iBAAiB,GAC5D,eAAe,YAAY;KAC7B,MAAM,EAAE,SAAS,gBAAgB,GAAG,eAAe,UAAU;KAG7D,IAAI,iBAAiB;AACrB,SAAI,iBACF,kBAAiB,oBAAoB;KAIvC,IAAI,kBAAkB;AACtB,UAAK,kBAEH,mBAAkB;cACT,kBACT,KAAI;AACF,wBAAkB,kBAChB,OAAO,UACP,iBACD;KACF,QAAO,CAEP;SAGD,mBAAkB,eAAe,OAAO,SAAS,KAC/C,eAAe,iBAAiB;AAIpC,SAAI,kBAAkB,gBACpB,aAAY,IAAI,YAAY;IAE/B;IAIH,MAAMoB,oBAAiC,CAAE;AACzC,SAAK,MAAM,OAAO,aAAa;KAC7B,MAAM,SAAS,QAAQ,IAAI,IAAI;AAC/B,SAAI,QAAQ;AACV,wBAAkB,KAAK,GAAG,OAAO;AACjC,cAAQ,OAAO,IAAI;AACnB,gBAAU,IAAI,IAAI;KACnB;IACF;AAGD,sBAAkB,KAAK,CAAC,GAAG,MAAM,EAAE,YAAY,EAAE,UAAU;AAG3D,SAAK,MAAM,kBAAkB,kBAC3B,MAAK,eAAe;AAItB,cAAU,IAAI,UAAU;AACxB,SAAK,OAAO;GACb,OAAM;IAEL,IAAI,SAAS,QAAQ,IAAI,UAAU;AACnC,SAAK,QAAQ;AACX,cAAS,CAAE;AACX,aAAQ,IAAI,WAAW,OAAO;IAC/B;AAED,WAAO,KAAK,OAAO;AAGnB,WAAO,OAAO,SAAS,cACrB,QAAO,OAAO;GAEjB;EACF;CACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/logtape",
-  "version": "1.1.0",
+  "version": "1.2.0-dev.341+a87baf94",
   "description": "Simple logging library with zero dependencies for Deno/Node.js/Bun/browsers",
   "keywords": [
     "logging",

package/src/sink.test.ts

@@ -1706,3 +1706,504 @@ test("fingersCrossed() - edge case: very deep category hierarchy", () => {
   assert(buffer.includes(parentRecord));
   assert(buffer.includes(deepError));
 });
+
+test("fingersCrossed() - context isolation basic functionality", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: { keys: ["requestId"] },
+  });
+
+  // Create records with different request IDs
+  const req1Debug: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-1", data: "debug1" },
+  };
+  const req1Info: LogRecord = {
+    ...info,
+    properties: { requestId: "req-1", data: "info1" },
+  };
+  const req1Error: LogRecord = {
+    ...error,
+    properties: { requestId: "req-1", data: "error1" },
+  };
+
+  const req2Debug: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-2", data: "debug2" },
+  };
+  const req2Info: LogRecord = {
+    ...info,
+    properties: { requestId: "req-2", data: "info2" },
+  };
+
+  // Buffer logs for both requests
+  sink(req1Debug);
+  sink(req1Info);
+  sink(req2Debug);
+  sink(req2Info);
+  assertEquals(buffer.length, 0); // All buffered
+
+  // Error in req-1 should only flush req-1 logs
+  sink(req1Error);
+  assertEquals(buffer.length, 3);
+  assertEquals(buffer[0], req1Debug);
+  assertEquals(buffer[1], req1Info);
+  assertEquals(buffer[2], req1Error);
+
+  // req-2 logs should still be buffered
+  buffer.length = 0;
+  sink(req2Debug); // Add another req-2 log
+  assertEquals(buffer.length, 0); // Still buffered
+
+  // Now trigger req-2
+  const req2Error: LogRecord = {
+    ...error,
+    properties: { requestId: "req-2", data: "error2" },
+  };
+  sink(req2Error);
+  assertEquals(buffer.length, 4); // 2x req2Debug + req2Info + req2Error
+  assertEquals(buffer[0], req2Debug);
+  assertEquals(buffer[1], req2Info);
+  assertEquals(buffer[2], req2Debug); // Second instance
+  assertEquals(buffer[3], req2Error);
+});
+
+test("fingersCrossed() - context isolation with multiple keys", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: { keys: ["requestId", "sessionId"] },
+  });
+
+  // Create records with different combinations
+  const record1: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-1", sessionId: "sess-1" },
+  };
+  const record2: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-1", sessionId: "sess-2" },
+  };
+  const record3: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-2", sessionId: "sess-1" },
+  };
+
+  sink(record1);
+  sink(record2);
+  sink(record3);
+  assertEquals(buffer.length, 0); // All buffered
+
+  // Error with req-1/sess-1 should only flush that combination
+  const trigger1: LogRecord = {
+    ...error,
+    properties: { requestId: "req-1", sessionId: "sess-1" },
+  };
+  sink(trigger1);
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[0], record1);
+  assertEquals(buffer[1], trigger1);
+
+  // Other combinations still buffered
+  buffer.length = 0;
+  const trigger2: LogRecord = {
+    ...error,
+    properties: { requestId: "req-1", sessionId: "sess-2" },
+  };
+  sink(trigger2);
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[0], record2);
+  assertEquals(buffer[1], trigger2);
+});
+
+test("fingersCrossed() - context isolation with missing keys", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: { keys: ["requestId"] },
+  });
+
+  // Records with and without requestId
+  const withId: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-1", other: "data" },
+  };
+  const withoutId: LogRecord = {
+    ...debug,
+    properties: { other: "data" },
+  };
+  const withUndefinedId: LogRecord = {
+    ...debug,
+    properties: { requestId: undefined, other: "data" },
+  };
+
+  sink(withId);
+  sink(withoutId);
+  sink(withUndefinedId);
+  assertEquals(buffer.length, 0); // All buffered
+
+  // Error without requestId should flush records without or with undefined requestId
+  const triggerNoId: LogRecord = {
+    ...error,
+    properties: { other: "data" },
+  };
+  sink(triggerNoId);
+  assertEquals(buffer.length, 3); // withoutId + withUndefinedId + triggerNoId
+  assertEquals(buffer[0], withoutId);
+  assertEquals(buffer[1], withUndefinedId);
+  assertEquals(buffer[2], triggerNoId);
+
+  // Records with requestId still buffered
+  buffer.length = 0;
+  const triggerWithId: LogRecord = {
+    ...error,
+    properties: { requestId: "req-1", other: "data" },
+  };
+  sink(triggerWithId);
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[0], withId);
+  assertEquals(buffer[1], triggerWithId);
+});
+
+test("fingersCrossed() - combined category and context isolation", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByCategory: "descendant",
+    isolateByContext: { keys: ["requestId"] },
+  });
+
+  // Create records with different categories and contexts
+  const appReq1: LogRecord = {
+    ...debug,
+    category: ["app"],
+    properties: { requestId: "req-1" },
+  };
+  const appModuleReq1: LogRecord = {
+    ...debug,
+    category: ["app", "module"],
+    properties: { requestId: "req-1" },
+  };
+  const appReq2: LogRecord = {
+    ...debug,
+    category: ["app"],
+    properties: { requestId: "req-2" },
+  };
+  const appModuleReq2: LogRecord = {
+    ...debug,
+    category: ["app", "module"],
+    properties: { requestId: "req-2" },
+  };
+  const otherReq1: LogRecord = {
+    ...debug,
+    category: ["other"],
+    properties: { requestId: "req-1" },
+  };
+
+  sink(appReq1);
+  sink(appModuleReq1);
+  sink(appReq2);
+  sink(appModuleReq2);
+  sink(otherReq1);
+  assertEquals(buffer.length, 0); // All buffered
+
+  // Error in ["app"] with req-1 should flush descendants with same requestId
+  const triggerAppReq1: LogRecord = {
+    ...error,
+    category: ["app"],
+    properties: { requestId: "req-1" },
+  };
+  sink(triggerAppReq1);
+  assertEquals(buffer.length, 3);
+  assertEquals(buffer[0], appReq1);
+  assertEquals(buffer[1], appModuleReq1);
+  assertEquals(buffer[2], triggerAppReq1);
+
+  // Other combinations still buffered
+  buffer.length = 0;
+  const triggerAppReq2: LogRecord = {
+    ...error,
+    category: ["app"],
+    properties: { requestId: "req-2" },
+  };
+  sink(triggerAppReq2);
+  assertEquals(buffer.length, 3);
+  assertEquals(buffer[0], appReq2);
+  assertEquals(buffer[1], appModuleReq2);
+  assertEquals(buffer[2], triggerAppReq2);
+});
+
+test("fingersCrossed() - context isolation buffer size limits", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    maxBufferSize: 2,
+    isolateByContext: { keys: ["requestId"] },
+  });
+
+  // Create records for different contexts
+  const req1Trace: LogRecord = {
+    ...trace,
+    properties: { requestId: "req-1" },
+  };
+  const req1Debug: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-1" },
+  };
+  const req1Info: LogRecord = {
+    ...info,
+    properties: { requestId: "req-1" },
+  };
+  const req2Trace: LogRecord = {
+    ...trace,
+    properties: { requestId: "req-2" },
+  };
+  const req2Debug: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-2" },
+  };
+
+  // Fill req-1 buffer beyond limit
+  sink(req1Trace);
+  sink(req1Debug);
+  sink(req1Info); // Should drop req1Trace
+
+  // Fill req-2 buffer
+  sink(req2Trace);
+  sink(req2Debug);
+
+  // Trigger req-1
+  const req1Error: LogRecord = {
+    ...error,
+    properties: { requestId: "req-1" },
+  };
+  sink(req1Error);
+
+  // Should only have the last 2 records plus error
+  assertEquals(buffer.length, 3);
+  assertEquals(buffer[0], req1Debug);
+  assertEquals(buffer[1], req1Info);
+  assertEquals(buffer[2], req1Error);
+
+  // Trigger req-2
+  buffer.length = 0;
+  const req2Error: LogRecord = {
+    ...error,
+    properties: { requestId: "req-2" },
+  };
+  sink(req2Error);
+
+  // req-2 buffer should still have both records
+  assertEquals(buffer.length, 3);
+  assertEquals(buffer[0], req2Trace);
+  assertEquals(buffer[1], req2Debug);
+  assertEquals(buffer[2], req2Error);
+});
+
+test("fingersCrossed() - context isolation with special values", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: { keys: ["value"] },
+  });
+
+  // Records with special values
+  const nullValue: LogRecord = {
+    ...debug,
+    properties: { value: null },
+  };
+  const undefinedValue: LogRecord = {
+    ...debug,
+    properties: { value: undefined },
+  };
+  const zeroValue: LogRecord = {
+    ...debug,
+    properties: { value: 0 },
+  };
+  const emptyString: LogRecord = {
+    ...debug,
+    properties: { value: "" },
+  };
+  const falseValue: LogRecord = {
+    ...debug,
+    properties: { value: false },
+  };
+
+  sink(nullValue);
+  sink(undefinedValue);
+  sink(zeroValue);
+  sink(emptyString);
+  sink(falseValue);
+  assertEquals(buffer.length, 0); // All buffered
+
+  // Trigger with null value
+  const triggerNull: LogRecord = {
+    ...error,
+    properties: { value: null },
+  };
+  sink(triggerNull);
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[0], nullValue);
+  assertEquals(buffer[1], triggerNull);
+
+  // Trigger with zero value
+  buffer.length = 0;
+  const triggerZero: LogRecord = {
+    ...error,
+    properties: { value: 0 },
+  };
+  sink(triggerZero);
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[0], zeroValue);
+  assertEquals(buffer[1], triggerZero);
+
+  // Trigger with false value
+  buffer.length = 0;
+  const triggerFalse: LogRecord = {
+    ...error,
+    properties: { value: false },
+  };
+  sink(triggerFalse);
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[0], falseValue);
+  assertEquals(buffer[1], triggerFalse);
+});
+
+test("fingersCrossed() - context isolation only (no category isolation)", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: { keys: ["requestId"] },
+  });
+
+  // Different categories, same context
+  const cat1Req1: LogRecord = {
+    ...debug,
+    category: ["cat1"],
+    properties: { requestId: "req-1" },
+  };
+  const cat2Req1: LogRecord = {
+    ...debug,
+    category: ["cat2"],
+    properties: { requestId: "req-1" },
+  };
+  const cat1Req2: LogRecord = {
+    ...debug,
+    category: ["cat1"],
+    properties: { requestId: "req-2" },
+  };
+
+  sink(cat1Req1);
+  sink(cat2Req1);
+  sink(cat1Req2);
+  assertEquals(buffer.length, 0); // All buffered
+
+  // Error in any category with req-1 should flush all req-1 logs
+  const triggerReq1: LogRecord = {
+    ...error,
+    category: ["cat3"],
+    properties: { requestId: "req-1" },
+  };
+  sink(triggerReq1);
+  assertEquals(buffer.length, 3);
+  assertEquals(buffer[0], cat1Req1);
+  assertEquals(buffer[1], cat2Req1);
+  assertEquals(buffer[2], triggerReq1);
+
+  // req-2 still buffered
+  buffer.length = 0;
+  const triggerReq2: LogRecord = {
+    ...error,
+    category: ["cat1"],
+    properties: { requestId: "req-2" },
+  };
+  sink(triggerReq2);
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[0], cat1Req2);
+  assertEquals(buffer[1], triggerReq2);
+});
+
+test("fingersCrossed() - context isolation with nested objects", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: { keys: ["user"] },
+  });
+
+  // Records with nested object values
+  const user1: LogRecord = {
+    ...debug,
+    properties: { user: { id: 1, name: "Alice" } },
+  };
+  const user1Same: LogRecord = {
+    ...debug,
+    properties: { user: { id: 1, name: "Alice" } },
+  };
+  const user2: LogRecord = {
+    ...debug,
+    properties: { user: { id: 2, name: "Bob" } },
+  };
+
+  sink(user1);
+  sink(user1Same);
+  sink(user2);
+  assertEquals(buffer.length, 0); // All buffered
+
+  // Trigger with same user object
+  const triggerUser1: LogRecord = {
+    ...error,
+    properties: { user: { id: 1, name: "Alice" } },
+  };
+  sink(triggerUser1);
+  assertEquals(buffer.length, 3);
+  assertEquals(buffer[0], user1);
+  assertEquals(buffer[1], user1Same);
+  assertEquals(buffer[2], triggerUser1);
+
+  // user2 still buffered
+  buffer.length = 0;
+  const triggerUser2: LogRecord = {
+    ...error,
+    properties: { user: { id: 2, name: "Bob" } },
+  };
+  sink(triggerUser2);
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[0], user2);
+  assertEquals(buffer[1], triggerUser2);
+});
+
+test("fingersCrossed() - context isolation after trigger", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: { keys: ["requestId"] },
+  });
+
+  // Trigger req-1 immediately
+  const req1Error: LogRecord = {
+    ...error,
+    properties: { requestId: "req-1" },
+  };
+  sink(req1Error);
+  assertEquals(buffer.length, 1);
+  assertEquals(buffer[0], req1Error);
+
+  // After trigger, req-1 logs pass through
+  const req1Debug: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-1" },
+  };
+  sink(req1Debug);
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[1], req1Debug);
+
+  // But req-2 logs are still buffered
+  const req2Debug: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-2" },
+  };
+  sink(req2Debug);
+  assertEquals(buffer.length, 2); // No change
+
+  // Until req-2 triggers
+  const req2Error: LogRecord = {
+    ...error,
+    properties: { requestId: "req-2" },
+  };
+  sink(req2Error);
+  assertEquals(buffer.length, 4);
+  assertEquals(buffer[2], req2Debug);
+  assertEquals(buffer[3], req2Error);
+});

package/src/sink.ts

@@ -491,6 +491,38 @@ export interface FingersCrossedOptions {
       triggerCategory: readonly string[],
       bufferedCategory: readonly string[],
     ) => boolean);
+
+  /**
+   * Enable context-based buffer isolation.
+   * When enabled, buffers are isolated based on specified context keys.
+   * This is useful for scenarios like HTTP request tracing where logs
+   * should be isolated per request.
+   *
+   * @example
+   * ```typescript
+   * fingersCrossed(sink, {
+   *   isolateByContext: { keys: ['requestId'] }
+   * })
+   * ```
+   *
+   * @example Combined with category isolation
+   * ```typescript
+   * fingersCrossed(sink, {
+   *   isolateByCategory: 'descendant',
+   *   isolateByContext: { keys: ['requestId', 'sessionId'] }
+   * })
+   * ```
+   *
+   * @default `undefined` (no context isolation)
+   * @since 1.2.0
+   */
+  readonly isolateByContext?: {
+    /**
+     * Context keys to use for isolation.
+     * Buffers will be separate for different combinations of these context values.
+     */
+    readonly keys: readonly string[];
+  };
 }
 
 /**
@@ -535,6 +567,7 @@ export function fingersCrossed(
   const triggerLevel = options.triggerLevel ?? "error";
   const maxBufferSize = Math.max(0, options.maxBufferSize ?? 1000);
   const isolateByCategory = options.isolateByCategory;
+  const isolateByContext = options.isolateByContext;
 
   // Validate trigger level early
   try {
@@ -604,8 +637,56 @@ export function fingersCrossed(
     return JSON.parse(key);
   }
 
+  // Helper function to extract context values from properties
+  function getContextKey(properties: Record<string, unknown>): string {
+    if (!isolateByContext || isolateByContext.keys.length === 0) {
+      return "";
+    }
+    const contextValues: Record<string, unknown> = {};
+    for (const key of isolateByContext.keys) {
+      if (key in properties) {
+        contextValues[key] = properties[key];
+      }
+    }
+    return JSON.stringify(contextValues);
+  }
+
+  // Helper function to generate buffer key
+  function getBufferKey(
+    category: readonly string[],
+    properties: Record<string, unknown>,
+  ): string {
+    const categoryKey = getCategoryKey(category);
+    if (!isolateByContext) {
+      return categoryKey;
+    }
+    const contextKey = getContextKey(properties);
+    return `${categoryKey}:${contextKey}`;
+  }
+
+  // Helper function to parse buffer key
+  function parseBufferKey(key: string): {
+    category: string[];
+    context: string;
+  } {
+    if (!isolateByContext) {
+      return { category: parseCategoryKey(key), context: "" };
+    }
+    // Find the separator between category and context
+    // The category part is JSON-encoded, so we need to find where it ends
+    // We look for "]:" which indicates end of category array and start of context
+    const separatorIndex = key.indexOf("]:");
+    if (separatorIndex === -1) {
+      // No context part, entire key is category
+      return { category: parseCategoryKey(key), context: "" };
+    }
+    const categoryPart = key.substring(0, separatorIndex + 1); // Include the ]
+    const contextPart = key.substring(separatorIndex + 2); // Skip ]:
+    return { category: parseCategoryKey(categoryPart), context: contextPart };
+  }
+
   // Buffer management
-  if (!isolateByCategory) {
+  if (!isolateByCategory && !isolateByContext) {
     // Single global buffer
     const buffer: LogRecord[] = [];
     let triggered = false;
@@ -640,15 +721,15 @@ export function fingersCrossed(
       }
     };
   } else {
-    // Category-isolated buffers
+    // Category and/or context-isolated buffers
     const buffers = new Map<string, LogRecord[]>();
     const triggered = new Set<string>();
 
     return (record: LogRecord) => {
-      const categoryKey = getCategoryKey(record.category);
+      const bufferKey = getBufferKey(record.category, record.properties);
 
-      // Check if this category is already triggered
-      if (triggered.has(categoryKey)) {
+      // Check if this buffer is already triggered
+      if (triggered.has(bufferKey)) {
         sink(record);
         return;
       }
@@ -659,16 +740,42 @@ export function fingersCrossed(
         const keysToFlush = new Set<string>();
 
         for (const [bufferedKey] of buffers) {
-          if (bufferedKey === categoryKey) {
+          if (bufferedKey === bufferKey) {
             keysToFlush.add(bufferedKey);
-          } else if (shouldFlushBuffer) {
-            const bufferedCategory = parseCategoryKey(bufferedKey);
-            try {
-              if (shouldFlushBuffer(record.category, bufferedCategory)) {
-                keysToFlush.add(bufferedKey);
+          } else {
+            const { category: bufferedCategory, context: bufferedContext } =
+              parseBufferKey(bufferedKey);
+            const { context: triggerContext } = parseBufferKey(bufferKey);
+
+            // Check context match
+            let contextMatches = true;
+            if (isolateByContext) {
+              contextMatches = bufferedContext === triggerContext;
+            }
+
+            // Check category match
+            let categoryMatches = false;
+            if (!isolateByCategory) {
+              // No category isolation, so all categories match if context matches
+              categoryMatches = contextMatches;
+            } else if (shouldFlushBuffer) {
+              try {
+                categoryMatches = shouldFlushBuffer(
+                  record.category,
+                  bufferedCategory,
+                );
+              } catch {
+                // Ignore errors from custom matcher
               }
-            } catch {
-              // Ignore errors from custom matcher
+            } else {
+              // Same category only
+              categoryMatches = getCategoryKey(record.category) ===
+                getCategoryKey(bufferedCategory);
+            }
+
+            // Both must match for the buffer to be flushed
+            if (contextMatches && categoryMatches) {
+              keysToFlush.add(bufferedKey);
             }
           }
         }
@@ -692,20 +799,20 @@ export function fingersCrossed(
           sink(bufferedRecord);
         }
 
-        // Mark trigger category as triggered and send trigger record
-        triggered.add(categoryKey);
+        // Mark trigger buffer as triggered and send trigger record
+        triggered.add(bufferKey);
         sink(record);
       } else {
         // Buffer the record
-        let buffer = buffers.get(categoryKey);
+        let buffer = buffers.get(bufferKey);
         if (!buffer) {
           buffer = [];
-          buffers.set(categoryKey, buffer);
+          buffers.set(bufferKey, buffer);
         }
 
         buffer.push(record);
 
-        // Enforce max buffer size per category
+        // Enforce max buffer size per buffer
         while (buffer.length > maxBufferSize) {
           buffer.shift();
         }