@dws-std/logger 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominus Web Services (DWS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/Dominus-Web-Service/std@main/packages/logger/logo-logger.png" alt="DWS Logger logo" width="200" />
+</p>
+
+# 🎯 DWS Logger
+
+Logging in Bun often means choosing between "fast but dumb" or "smart but blocking".
+`@dws-std/logger` gives you both: a type-safe, sink-based system that never blocks your main thread.
+
+## Why this package?
+
+The goal is simple: **Stop your logs from slowing down your app.**
+
+Most loggers either block on every write or lose type safety when you need structured logging.
+This package runs everything in a worker thread, batches automatically, and still gives you full TypeScript inference on what you log.
+
+## 📌 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [Custom Sinks](#-custom-sinks)
+- [Type-Safe Logging](#-type-safe-logging)
+- [Error Handling](#-error-handling)
+- [Flushing and Closing](#-flushing-and-closing)
+- [Configuration](#-configuration)
+- [API Reference](#-api-reference)
+- [License](#-license)
+- [Contact](#-contact)
+
+## ✨ Features
+
+- ⚡ **Zero Blocking** : Every log goes through a worker thread – your main loop stays fast.
+- 🔒 **Type-Safe** : TypeScript infers the shape of your logs. No more `any` everywhere.
+- 🎯 **Sink Pattern** : Route logs to console, file, database, or your own custom destination.
+- 🔄 **Smart Batching** : Logs are grouped automatically for better I/O performance.
+- 🔔 **Event-Driven** : Listen to flush, close, and error events when you need them.
+
+## 🔧 Installation
+
+```bash
+bun add @dws-std/logger
+```
+
+## ⚙️ Usage
+
+### Basic Setup
+
+Create a logger, attach a sink, and start logging:
+
+```ts
+import { Logger, consoleSink } from '@dws-std/logger';
+
+// Create a logger and register a console sink
+const logger = new Logger().registerSink('console', consoleSink);
+
+// Log messages (always pass an object)
+logger.info({ message: 'Application started' });
+logger.warn({ message: 'This is a warning' });
+logger.error({ message: 'An error occurred', code: 500 });
+logger.debug({ action: 'debug_info', data: { foo: 'bar' } });
+logger.log({ event: 'generic_log' });
+
+// Close the logger when done
+await logger.close();
+```
+
+> ℹ️ Sinks are **factory functions**, not classes. You pass the factory itself (not the
+> result of calling it) to `registerSink`. The worker re-evaluates the factory string
+> and calls it with the `sinkArgs` you forwarded, so the sink is built **inside** the worker.
+
+### Multiple Sinks
+
+Need logs going to different places? Register as many sinks as you want:
+
+```ts
+import { Logger, consoleSink, fileSink } from '@dws-std/logger';
+
+// Register multiple sinks
+const logger = new Logger()
+	.registerSink('console', consoleSink)
+	.registerSink('file', fileSink, './app.log');
+
+// Log to all sinks
+logger.info({ message: 'This goes to console and file' });
+
+// Log to specific sinks only
+logger.error({ message: 'Only in file' }, ['file']);
+logger.warn({ message: 'Only in console' }, ['console']);
+
+await logger.close();
+```
+
+### Built-in Sinks
+
+| Factory      | Args        | Description                                                |
+| ------------ | ----------- | --------------------------------------------------------- |
+| `consoleSink`| _none_      | Writes JSON log entries to `console` (routed by level).   |
+| `fileSink`   | `path`      | Appends JSON log entries to a file via `Bun.FileSink`.    |
+| `devNullSink`| _none_      | Discards everything – useful for benchmarks / dry runs.  |
+
+```ts
+import { Logger, devNullSink, fileSink } from '@dws-std/logger';
+
+const logger = new Logger()
+	.registerSink('applog', fileSink, './app.log')
+	.registerSink('silent', devNullSink);
+```
+
+## 🛠️ Custom Sinks
+
+A sink is a plain object implementing the `LoggerSink` interface — register a **factory**
+function that builds and returns it. The factory is stringify-ed and re-evaluated inside the
+worker, so its body must be **self-contained**: it may use its arguments, runtime globals
+(`Bun`, `console`, `JSON`, …) and dynamic `import()`, but **must not** close over
+module-scoped imports or variables from the calling file.
+
+```ts
+import { Logger, type SinkFactory } from '@dws-std/logger';
+
+// A self-contained factory: no module-scoped imports captured.
+const databaseSink: SinkFactory<{ query: string }, [dbUrl: string]> = (dbUrl: string) => {
+	// Open the connection inside the factory — the worker owns it.
+	const connection = /* …open using `dbUrl`… */ {} as unknown;
+	return {
+		async log(level, timestamp, object) {
+			// object is typed as { query: string }
+			await (connection as { write: (s: string) => Promise<void> }).write(
+				JSON.stringify({ level, timestamp, object })
+			);
+		},
+		async close() {
+			await (connection as { close: () => Promise<void> }).close();
+		}
+	};
+};
+
+const logger = new Logger().registerSink('database', databaseSink, 'postgres://localhost/app');
+
+logger.info({ query: 'SELECT 1' });
+await logger.close();
+```
+
+### The `LoggerSink` interface
+
+```ts
+interface LoggerSink<TLogObject = unknown> {
+	log(level: LogLevels, timestamp: number, object: TLogObject): Promise<void> | void;
+	flush?(): Promise<void> | void; // called by Logger.flush()
+	close?(): Promise<void> | void; // called on Logger.close()
+}
+```
+
+- `log` is the only required method.
+- `flush` is optional — implement it when your sink buffers writes and you want `logger.flush()` to push them through.
+- `close` is optional — implement it to release file handles, connections, etc.
+
+## 🔒 Type-Safe Logging
+
+When you define typed sinks, TypeScript knows exactly what shape your logs need. No more
+guessing, no more runtime surprises.
+
+### Single Typed Sink
+
+```ts
+import { Logger, type LoggerSink, type LogLevels, type SinkFactory } from '@dws-std/logger';
+
+interface UserLog {
+	userId: number;
+	action: string;
+	timestamp?: Date;
+}
+
+// Typed factory: the returned sink only accepts UserLog objects.
+const userLogSink: SinkFactory<UserLog> = () => ({
+	log(level: LogLevels, timestamp: number, object: UserLog): void {
+		console.log(`User ${object.userId} performed: ${object.action}`);
+	}
+});
+
+const logger = new Logger().registerSink('userLog', userLogSink);
+
+// ✅ TypeScript requires the correct shape
+logger.info({ userId: 123, action: 'login' });
+
+// ❌ TypeScript error: Missing required property 'action'
+logger.info({ userId: 123 });
+```
+
+### Multiple Typed Sinks
+
+When logging to multiple sinks at once, TypeScript creates an intersection of all the
+targeted sinks' types — you must satisfy every one of them.
+
+```ts
+interface UserLog {
+	userId: number;
+	action: string;
+}
+
+interface ApiLog {
+	endpoint: string;
+	method: string;
+	statusCode: number;
+}
+
+const userLogSink: SinkFactory<UserLog> = () => ({
+	async log(_level, _ts, object) {
+		// … persist object …
+		void object;
+	}
+});
+
+const apiLogSink: SinkFactory<ApiLog> = () => ({
+	async log(_level, _ts, object) {
+		// … persist object …
+		void object;
+	}
+});
+
+const logger = new Logger()
+	.registerSink('user', userLogSink)
+	.registerSink('api', apiLogSink);
+
+// ✅ Logging to both sinks requires BOTH types combined
+logger.info(
+	{
+		userId: 123,
+		action: 'api_call',
+		endpoint: '/users',
+		method: 'POST',
+		statusCode: 201
+	},
+	['user', 'api']
+);
+
+// ✅ Logging to only one sink requires only that sink's type
+logger.warn({ userId: 456, action: 'failed_attempt' }, ['user']);
+
+// ❌ TypeScript error: Missing api properties
+logger.error({ userId: 789, action: 'error' }, ['user', 'api']);
+```
+
+### Mixing Typed and Untyped Sinks
+
+When you mix typed sinks with untyped ones (like `consoleSink`, which accepts `unknown`),
+things stay flexible: the intersection with `unknown` lets extra properties through.
+
+```ts
+import { Logger, consoleSink, type SinkFactory } from '@dws-std/logger';
+
+interface DatabaseLog {
+	query: string;
+	duration: number;
+}
+
+const databaseLogSink: SinkFactory<DatabaseLog> = () => ({
+	async log(_level, _ts, object) {
+		// … persist object …
+		void object;
+	}
+});
+
+const logger = new Logger()
+	.registerSink('database', databaseLogSink)
+	.registerSink('console', consoleSink); // accepts unknown
+
+// ✅ Works — the database type is enforced, console accepts anything
+logger.info(
+	{
+		query: 'SELECT * FROM users',
+		duration: 123,
+		customData: 'anything goes'
+	},
+	['database', 'console']
+);
+```
+
+## 🚨 Error Handling
+
+Things break. When they do, you'll want to know:
+
+```ts
+import { Logger, consoleSink } from '@dws-std/logger';
+
+const logger = new Logger().registerSink('console', consoleSink);
+
+// Listen for sink errors (a sink throwing inside the worker)
+logger.addListener('sinkError', (error) => {
+	console.error('Logger error:', error.message);
+});
+
+// Listen for sink registration errors (factory failed to build inside the worker)
+logger.addListener('registerSinkError', (error) => {
+	console.error('Failed to register sink:', error.message);
+});
+
+logger.info({ message: 'Safe to log' });
+await logger.close();
+```
+
+## 🧹 Flushing and Closing
+
+When you need to make sure everything is written before shutting down:
+
+```ts
+import { Logger, consoleSink } from '@dws-std/logger';
+
+const logger = new Logger().registerSink('console', consoleSink);
+
+logger.info({ message: 'First message' });
+logger.info({ message: 'Second message' });
+
+// Wait for all pending logs to be processed
+await logger.flush();
+
+// Close the logger and release resources (internally calls flush)
+await logger.close();
+```
+
+`flush()` drains both the in-memory queue **and** each sink's own buffer (via the
+optional `flush()` method on `LoggerSink`).
+
+## ⚙️ Configuration
+
+Fine-tune the batching and queue behavior:
+
+```ts
+import { Logger, consoleSink } from '@dws-std/logger';
+
+const logger = new Logger({
+	maxPendingLogs: 10_000, // Max queued logs (default: 10,000)
+	batchSize: 100, // Logs per batch (default: 100)
+	batchTimeout: 0.1, // Ms before flushing a partial batch (default: 0.1)
+	maxMessagesInFlight: 100, // Max batches being processed (default: 100)
+	autoEnd: true, // Auto-close on process exit (default: true)
+	flushOnBeforeExit: true // Flush before exit (default: true)
+}).registerSink('console', consoleSink);
+```
+
+## 📚 API Reference
+
+Full docs: [https://dominus-web-service.github.io/std/](https://dominus-web-service.github.io/std/)
+
+## ⚖️ License
+
+MIT - Feel free to use it.
+
+## 📧 Contact
+
+- GitHub: [Dominus-Web-Service](https://github.com/Dominus-Web-Service/packages)

package/dist/events/logger-events.d.ts

@@ -0,0 +1,21 @@
+import type { EventMap } from '@dws-std/common';
+import type { Exception } from '@dws-std/error';
+export interface LoggerEvent extends EventMap {
+    onBeforeExitError: [Exception<{
+        error: Error;
+    }>];
+    registerSinkError: [
+        Exception<{
+            sinkName: string;
+            error: Error;
+        }>
+    ];
+    sinkError: [
+        Exception<{
+            sinkName: string;
+            object?: unknown;
+            error: Error;
+        }>
+    ];
+    drained: [];
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { LOGGER_ERROR_KEYS, Logger, type LoggerOptions } from './logger';
+export { consoleSink } from './sinks/console-logger';
+export { devNullSink } from './sinks/devnull-logger';
+export { fileSink } from './sinks/file-logger';
+export type { LogLevels } from './types/log-levels';
+export type { LoggerSink } from './types/logger-sink';
+export type { SinkFactory } from './types/sink-factory';

package/dist/index.js

@@ -0,0 +1,448 @@
+// @bun
+// src/logger.ts
+import { TypedEventEmitter } from "@dws-std/common";
+import { Exception } from "@dws-std/error";
+
+// src/worker-logger.ts
+var workerFunction = () => {
+  const sinks = {};
+  const self = globalThis;
+  const processLogEntry = (log) => {
+    const { sinkNames, level, timestamp, object } = log;
+    const len = sinkNames.length;
+    let promises;
+    for (let i = 0;i < len; ++i) {
+      const sinkName = sinkNames[i];
+      if (sinkName === undefined)
+        continue;
+      const sink = sinks[sinkName];
+      if (!sink)
+        continue;
+      try {
+        const result = sink.log(level, timestamp, object);
+        if (result instanceof Promise) {
+          const guarded = result.catch((error) => {
+            self.postMessage({
+              type: "SINK_LOG_ERROR",
+              sinkName,
+              error,
+              object
+            });
+          });
+          (promises ??= []).push(guarded);
+        }
+      } catch (error) {
+        self.postMessage({
+          type: "SINK_LOG_ERROR",
+          sinkName,
+          error,
+          object
+        });
+      }
+    }
+    return promises === undefined ? undefined : Promise.all(promises).then(() => {
+      return;
+    });
+  };
+  self.addEventListener("message", (event) => {
+    switch (event.data.type) {
+      case "REGISTER_SINK": {
+        const { sinkName, sinkFactoryString, sinkArgs } = event.data;
+        try {
+          const create = new Function("sinkArgs", `return (${sinkFactoryString})(...sinkArgs);`);
+          sinks[sinkName] = create(sinkArgs);
+        } catch (error) {
+          self.postMessage({
+            type: "REGISTER_SINK_ERROR",
+            sinkName,
+            error
+          });
+        }
+        break;
+      }
+      case "LOG_BATCH": {
+        const { logs } = event.data;
+        const len = logs.length;
+        let pending;
+        for (let i = 0;i < len; ++i) {
+          const result = processLogEntry(logs[i]);
+          if (result !== undefined)
+            (pending ??= []).push(result);
+        }
+        if (pending === undefined)
+          self.postMessage({ type: "BATCH_COMPLETE" });
+        else
+          Promise.all(pending).then(() => self.postMessage({ type: "BATCH_COMPLETE" }));
+        break;
+      }
+      case "FLUSH": {
+        let pending;
+        for (const [sinkName, sink] of Object.entries(sinks))
+          try {
+            const result = sink.flush?.();
+            if (result instanceof Promise) {
+              const guarded = result.catch((error) => {
+                self.postMessage({
+                  type: "SINK_LOG_ERROR",
+                  sinkName,
+                  error,
+                  object: undefined
+                });
+              });
+              (pending ??= []).push(guarded);
+            }
+          } catch (error) {
+            self.postMessage({
+              type: "SINK_LOG_ERROR",
+              sinkName,
+              error,
+              object: undefined
+            });
+          }
+        if (pending === undefined)
+          self.postMessage({ type: "FLUSH_COMPLETE" });
+        else
+          Promise.all(pending).then(() => self.postMessage({ type: "FLUSH_COMPLETE" }));
+        break;
+      }
+      case "CLOSE": {
+        const entries = Object.entries(sinks);
+        for (const [name, sink] of entries)
+          try {
+            sink.close?.();
+          } catch (error) {
+            self.postMessage({
+              type: "SINK_CLOSE_ERROR",
+              sinkName: name,
+              error
+            });
+          }
+        self.postMessage({ type: "CLOSE_COMPLETE" });
+        break;
+      }
+      default:
+        break;
+    }
+  });
+};
+
+// src/logger.ts
+var LOGGER_ERROR_KEYS = {
+  SINK_ALREADY_ADDED: "logger.sink-already-added",
+  NO_SINKS_PROVIDED: "logger.no-sinks-provided",
+  SINK_LOG_ERROR: "logger.sink-log-error",
+  SINK_CLOSE_ERROR: "logger.sink-close-error",
+  REGISTER_SINK_ERROR: "logger.register-sink-error",
+  BEFORE_EXIT_FLUSH_ERROR: "logger.before-exit-flush-error",
+  BEFORE_EXIT_CLOSE_ERROR: "logger.before-exit-close-error"
+};
+
+class Logger extends TypedEventEmitter {
+  sinks;
+  sinkKeys = [];
+  worker;
+  workerUrl;
+  maxPendingLogs;
+  maxMessagesInFlight;
+  batchSize;
+  batchTimeout;
+  autoEnd;
+  flushOnBeforeExit;
+  pendingLogs = [];
+  pendingHead = 0;
+  messagesInFlight = 0;
+  batchTimer = null;
+  isWriting = false;
+  flushResolvers = [];
+  flushingResolvers = [];
+  flushPending = false;
+  closeResolver = null;
+  backpressureResolver = null;
+  workerTerminated = false;
+  handleExit = () => {
+    this.terminateWorker();
+  };
+  handleWorkerClose = () => {
+    process.off("beforeExit", this.handleBeforeExit);
+    process.off("exit", this.handleExit);
+  };
+  constructor({
+    autoEnd = true,
+    batchSize = 100,
+    batchTimeout = 0.1,
+    flushOnBeforeExit = true,
+    maxMessagesInFlight = 100,
+    maxPendingLogs = 1e4
+  } = {}) {
+    super();
+    this.sinks = {};
+    this.maxPendingLogs = maxPendingLogs;
+    this.maxMessagesInFlight = maxMessagesInFlight;
+    this.batchSize = batchSize;
+    this.batchTimeout = batchTimeout;
+    this.autoEnd = autoEnd;
+    this.flushOnBeforeExit = flushOnBeforeExit;
+    this.workerUrl = URL.createObjectURL(new Blob([`(${workerFunction.toString()})()`], { type: "application/javascript" }));
+    this.worker = new Worker(this.workerUrl, { type: "module" });
+    this.setupWorkerMessages();
+    if (this.autoEnd)
+      this.setupAutoEnd();
+  }
+  registerSink(sinkName, sinkFactory, ...sinkArgs) {
+    if (this.sinks[sinkName] !== undefined)
+      throw new Exception("Sink is already registered", {
+        key: LOGGER_ERROR_KEYS.SINK_ALREADY_ADDED,
+        cause: { sinkName }
+      });
+    this.worker.postMessage({
+      type: "REGISTER_SINK",
+      sinkName,
+      sinkFactoryString: sinkFactory.toString(),
+      sinkArgs
+    });
+    this.sinks[sinkName] = sinkFactory;
+    this.sinkKeys.push(sinkName);
+    return this;
+  }
+  error(object, sinkNames = this.sinkKeys) {
+    this.enqueue("ERROR", object, sinkNames);
+  }
+  warn(object, sinkNames = this.sinkKeys) {
+    this.enqueue("WARN", object, sinkNames);
+  }
+  info(object, sinkNames = this.sinkKeys) {
+    this.enqueue("INFO", object, sinkNames);
+  }
+  debug(object, sinkNames = this.sinkKeys) {
+    this.enqueue("DEBUG", object, sinkNames);
+  }
+  log(object, sinkNames = this.sinkKeys) {
+    this.enqueue("LOG", object, sinkNames);
+  }
+  flush() {
+    return new Promise((resolve) => {
+      this.flushResolvers.push(resolve);
+      this.tryFlush();
+    });
+  }
+  async close() {
+    await this.flush();
+    return new Promise((resolve) => {
+      this.closeResolver = resolve;
+      this.worker.postMessage({ type: "CLOSE" });
+    });
+  }
+  enqueue(level, object, sinkNames) {
+    if (this.sinkKeys.length === 0)
+      throw new Exception("No sinks provided", {
+        key: LOGGER_ERROR_KEYS.NO_SINKS_PROVIDED,
+        cause: { level, object }
+      });
+    const pendingLength = this.pendingLogs.length - this.pendingHead;
+    if (pendingLength >= this.maxPendingLogs)
+      return;
+    this.pendingLogs.push({
+      sinkNames: sinkNames ?? this.sinkKeys,
+      level,
+      timestamp: Date.now(),
+      object
+    });
+    if (pendingLength + 1 >= this.batchSize) {
+      if (this.batchTimer !== null) {
+        clearTimeout(this.batchTimer);
+        this.batchTimer = null;
+      }
+      this.triggerProcessing();
+    } else if (this.batchTimer === null && this.batchTimeout > 0)
+      this.batchTimer = setTimeout(() => {
+        this.batchTimer = null;
+        this.triggerProcessing();
+      }, this.batchTimeout);
+  }
+  triggerProcessing() {
+    if (this.isWriting)
+      return;
+    this.isWriting = true;
+    this.processPendingLogs();
+  }
+  async processPendingLogs() {
+    while (this.pendingLogs.length - this.pendingHead > 0) {
+      if (this.messagesInFlight >= this.maxMessagesInFlight)
+        await new Promise((resolve) => {
+          this.backpressureResolver = resolve;
+        });
+      const end = Math.min(this.pendingHead + this.batchSize, this.pendingLogs.length);
+      const batch = this.pendingLogs.slice(this.pendingHead, end);
+      this.pendingHead = end;
+      this.reclaimPending();
+      this.messagesInFlight++;
+      this.worker.postMessage({
+        type: "LOG_BATCH",
+        logs: batch
+      });
+    }
+    this.isWriting = false;
+    this.emit("drained");
+  }
+  reclaimPending() {
+    if (this.pendingHead === this.pendingLogs.length) {
+      this.pendingLogs.length = 0;
+      this.pendingHead = 0;
+    } else if (this.pendingHead > this.batchSize && this.pendingHead * 2 >= this.pendingLogs.length) {
+      this.pendingLogs.splice(0, this.pendingHead);
+      this.pendingHead = 0;
+    }
+  }
+  releaseBatch() {
+    this.messagesInFlight--;
+    if (this.backpressureResolver !== null) {
+      this.backpressureResolver();
+      this.backpressureResolver = null;
+    }
+  }
+  tryFlush() {
+    if (this.flushResolvers.length === 0)
+      return;
+    if (this.pendingLogs.length - this.pendingHead > 0) {
+      if (!this.isWriting) {
+        this.isWriting = true;
+        this.processPendingLogs();
+      }
+      return;
+    }
+    if (this.messagesInFlight === 0 && !this.flushPending) {
+      this.flushPending = true;
+      this.flushingResolvers.push(...this.flushResolvers);
+      this.flushResolvers.length = 0;
+      this.worker.postMessage({ type: "FLUSH" });
+    }
+  }
+  setupWorkerMessages() {
+    this.worker.addEventListener("message", (event) => {
+      switch (event.data.type) {
+        case "BATCH_COMPLETE":
+          this.releaseBatch();
+          this.tryFlush();
+          break;
+        case "FLUSH_COMPLETE": {
+          this.flushPending = false;
+          const resolvers = this.flushingResolvers.splice(0, this.flushingResolvers.length);
+          for (const resolve of resolvers)
+            resolve();
+          this.tryFlush();
+          break;
+        }
+        case "SINK_LOG_ERROR":
+          this.emit("sinkError", new Exception("Sink failed to log message", {
+            key: LOGGER_ERROR_KEYS.SINK_LOG_ERROR,
+            cause: {
+              sinkName: event.data.sinkName,
+              object: event.data.object,
+              error: event.data.error
+            }
+          }));
+          break;
+        case "SINK_CLOSE_ERROR":
+          this.emit("sinkError", new Exception("Sink failed to close", {
+            key: LOGGER_ERROR_KEYS.SINK_CLOSE_ERROR,
+            cause: { sinkName: event.data.sinkName, error: event.data.error }
+          }));
+          break;
+        case "REGISTER_SINK_ERROR":
+          this.emit("registerSinkError", new Exception("Failed to register sink", {
+            key: LOGGER_ERROR_KEYS.REGISTER_SINK_ERROR,
+            cause: { sinkName: event.data.sinkName, error: event.data.error }
+          }));
+          break;
+        case "CLOSE_COMPLETE":
+          this.terminateWorker();
+          if (this.closeResolver) {
+            this.closeResolver();
+            this.closeResolver = null;
+          }
+          break;
+        default:
+          break;
+      }
+    });
+  }
+  terminateWorker() {
+    if (this.workerTerminated)
+      return;
+    this.workerTerminated = true;
+    this.worker.terminate();
+    URL.revokeObjectURL(this.workerUrl);
+  }
+  setupAutoEnd() {
+    process.on("beforeExit", this.handleBeforeExit);
+    process.on("exit", this.handleExit);
+    this.worker.addEventListener("close", this.handleWorkerClose);
+  }
+  handleBeforeExit = () => {
+    if (this.flushOnBeforeExit)
+      this.flush().then(() => this.close()).catch((error) => {
+        this.emit("onBeforeExitError", new Exception("Failed to flush before exit", {
+          key: LOGGER_ERROR_KEYS.BEFORE_EXIT_FLUSH_ERROR,
+          cause: { error }
+        }));
+      });
+    else
+      this.close().catch((error) => {
+        this.emit("onBeforeExitError", new Exception("Failed to close before exit", {
+          key: LOGGER_ERROR_KEYS.BEFORE_EXIT_CLOSE_ERROR,
+          cause: { error }
+        }));
+      });
+  };
+}
+// src/sinks/console-logger.ts
+var consoleSink = () => ({
+  log(level, timestamp, object) {
+    const logEntry = { timestamp, level, content: object };
+    const logLevel = level.toLowerCase();
+    const methods = {
+      error: console.error,
+      warn: console.warn,
+      info: console.info,
+      debug: console.debug,
+      log: console.log,
+      trace: console.trace
+    };
+    methods[logLevel](JSON.stringify(logEntry));
+  }
+});
+// src/sinks/devnull-logger.ts
+var devNullSink = () => ({
+  log() {}
+});
+// src/sinks/file-logger.ts
+var fileSink = (path) => {
+  const sink = Bun.file(path).writer();
+  let isClosed = false;
+  return {
+    log(level, timestamp, object) {
+      if (isClosed)
+        return;
+      sink.write(JSON.stringify({ timestamp, level, content: object }) + `
+`);
+    },
+    async flush() {
+      if (isClosed)
+        return;
+      await sink.flush();
+    },
+    async close() {
+      if (isClosed)
+        return;
+      isClosed = true;
+      await sink.end();
+    }
+  };
+};
+export {
+  fileSink,
+  devNullSink,
+  consoleSink,
+  Logger,
+  LOGGER_ERROR_KEYS
+};

package/dist/logger.d.ts

@@ -0,0 +1,213 @@
+import { TypedEventEmitter } from '@dws-std/common';
+import type { LoggerEvent } from './events/logger-events';
+import type { LoggerSink } from './types/logger-sink';
+import type { SinkBodiesIntersection } from './types/sink-bodies-intersection';
+import type { SinkMap } from './types/sink-map';
+/**
+ * Configuration options for the {@link Logger} constructor.
+ */
+export interface LoggerOptions {
+    /**
+     * Maximum number of log messages that can be queued in memory before dropping new logs.
+     * @default 10_000
+     */
+    maxPendingLogs?: number;
+    /**
+     * Maximum number of messages that can be sent to the worker without acknowledgment.
+     * Controls backpressure to prevent overwhelming the worker thread.
+     * @default 100
+     */
+    maxMessagesInFlight?: number;
+    /**
+     * Maximum number of logs to batch together before sending to the worker.
+     * Higher values = better throughput but higher latency.
+     * @default 100
+     */
+    batchSize?: number;
+    /**
+     * Maximum time in milliseconds to wait before flushing a partial batch.
+     * Prevents logs from being delayed indefinitely when batch size is not reached.
+     * Set to 0 to disable time-based flushing.
+     * @default 0.1 (milliseconds)
+     */
+    batchTimeout?: number;
+    /**
+     * Whether to automatically flush and close the logger when the process exits.
+     * When enabled, hooks are installed on `process.on('beforeExit')` and `process.on('exit')`.
+     * @default true
+     */
+    autoEnd?: boolean;
+    /**
+     * Whether to flush pending logs before the process exits.
+     * Only applies when `autoEnd` is true.
+     * @default true
+     */
+    flushOnBeforeExit?: boolean;
+}
+export declare const LOGGER_ERROR_KEYS: {
+    readonly SINK_ALREADY_ADDED: "logger.sink-already-added";
+    readonly NO_SINKS_PROVIDED: "logger.no-sinks-provided";
+    readonly SINK_LOG_ERROR: "logger.sink-log-error";
+    readonly SINK_CLOSE_ERROR: "logger.sink-close-error";
+    readonly REGISTER_SINK_ERROR: "logger.register-sink-error";
+    readonly BEFORE_EXIT_FLUSH_ERROR: "logger.before-exit-flush-error";
+    readonly BEFORE_EXIT_CLOSE_ERROR: "logger.before-exit-close-error";
+};
+export declare class Logger<TSinks extends SinkMap = Record<never, never>> extends TypedEventEmitter<LoggerEvent> {
+    /** Map of registered sinks (logging destinations) */
+    private readonly sinks;
+    /** List of registered sink keys for quick access */
+    private readonly sinkKeys;
+    /** Worker instance handling log processing */
+    private readonly worker;
+    /** Object URL backing the worker module, revoked once the worker has loaded */
+    private readonly workerUrl;
+    /** Maximum number of pending log messages allowed in the queue */
+    private readonly maxPendingLogs;
+    /** Maximum number of messages in flight to the worker */
+    private readonly maxMessagesInFlight;
+    /** Number of logs to batch before sending to worker */
+    private readonly batchSize;
+    /** Timeout in milliseconds before flushing incomplete batch */
+    private readonly batchTimeout;
+    /** Whether to auto flush and close on process exit */
+    private readonly autoEnd;
+    /** Whether to flush before process exit */
+    private readonly flushOnBeforeExit;
+    /** Backing buffer of pending log messages (consumed from {@link pendingHead}) */
+    private readonly pendingLogs;
+    /** Index of the first not-yet-dispatched entry in {@link pendingLogs} */
+    private pendingHead;
+    /** Number of log messages currently being processed by the worker */
+    private messagesInFlight;
+    /** Timer for batching log messages */
+    private batchTimer;
+    /** Whether the logger is currently writing log messages to the worker */
+    private isWriting;
+    /** Resolvers for flush promises awaiting the next flush round */
+    private readonly flushResolvers;
+    /** Resolvers captured by the flush round currently in flight */
+    private readonly flushingResolvers;
+    /** Whether a FLUSH round-trip is currently in flight to the worker */
+    private flushPending;
+    /** Resolver for the close promise */
+    private closeResolver;
+    /** Resolver for backpressure when maxMessagesInFlight is reached */
+    private backpressureResolver;
+    /** Whether the worker has already been terminated (guards double teardown) */
+    private workerTerminated;
+    /** Handle the exit event */
+    private readonly handleExit;
+    /** Handle the worker close event */
+    private readonly handleWorkerClose;
+    /**
+     * Creates a new Logger instance with the specified options.
+     *
+     * @param options - Configuration options for the logger
+     */
+    constructor({ autoEnd, batchSize, batchTimeout, flushOnBeforeExit, maxMessagesInFlight, maxPendingLogs }?: LoggerOptions);
+    /**
+     * Registers a new sink (logging destination) with the logger.
+     *
+     * The factory is serialized and re-evaluated inside the worker, so its body must
+     * be self-contained (no module-scoped imports captured by closure).
+     *
+     * @param sinkName - The name of the sink
+     * @param sinkFactory - The factory building the sink
+     * @param sinkArgs - The factory arguments
+     *
+     * @returns The logger instance with new type (for chaining)
+     */
+    registerSink<TSinkName extends string, TSink extends LoggerSink, TSinkArgs extends unknown[]>(sinkName: TSinkName, sinkFactory: (...args: TSinkArgs) => TSink, ...sinkArgs: TSinkArgs): Logger<TSinks & Record<TSinkName, (...args: TSinkArgs) => TSink>>;
+    /**
+     * Logs a message at the ERROR level to the specified sinks.
+     *
+     * @param object - The log message object
+     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
+     */
+    error<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
+    /**
+     * Logs a message at the WARN level to the specified sinks.
+     *
+     * @param object - The log message object
+     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
+     */
+    warn<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
+    /**
+     * Logs a message at the INFO level to the specified sinks.
+     *
+     * @param object - The log message object
+     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
+     */
+    info<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
+    /**
+     * Logs a message at the DEBUG level to the specified sinks.
+     *
+     * @param object - The log message object
+     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
+     */
+    debug<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
+    /**
+     * Logs a message at the TRACE level to the specified sinks.
+     *
+     * @param object - The log message object
+     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
+     */
+    log<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
+    /**
+     * Flushes all pending logs and the sinks' buffers, and waits for completion.
+     */
+    flush(): Promise<void>;
+    /**
+     * Closes the logger, flushes pending logs, and releases resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Enqueues a log message to be processed by the worker.
+     *
+     * @param level - The log level
+     * @param object - The log message object
+     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
+     */
+    private enqueue;
+    /**
+     * Triggers processing of pending logs.
+     */
+    private triggerProcessing;
+    /**
+     * Processes pending log messages by sending them to the worker in batches.
+     */
+    private processPendingLogs;
+    /**
+     * Reclaims consumed slots in the pending buffer.
+     * Fully resets the buffer when drained, otherwise compacts only once the consumed
+     * prefix dominates the backing array, keeping dequeue amortized O(1).
+     */
+    private reclaimPending;
+    /**
+     * Releases a batch by decrementing the in-flight counter and resolving backpressure if needed.
+     */
+    private releaseBatch;
+    /**
+     * Advances the flush state machine: drains pending logs, then asks the worker to
+     * flush the sinks' buffers once everything has been dispatched and acknowledged.
+     */
+    private tryFlush;
+    /**
+     * Sets up message handling for the worker.
+     */
+    private setupWorkerMessages;
+    /**
+     * Terminates the worker and releases the object URL backing its module.
+     * Idempotent: safe to call from both the close handshake and process exit.
+     */
+    private terminateWorker;
+    /**
+     * Sets up automatic flushing and closing of the logger on process exit.
+     */
+    private setupAutoEnd;
+    /**
+     * Handles the beforeExit event.
+     */
+    private readonly handleBeforeExit;
+}

package/dist/sinks/console-logger.d.ts

@@ -0,0 +1,8 @@
+import type { LoggerSink } from '#/types/logger-sink';
+/**
+ * Creates a sink that writes JSON log entries to the console, routed to the
+ * matching `console` method for each level (`error`, `warn`, `info`, …).
+ *
+ * @typeParam TLogObject - The shape of the objects this sink accepts.
+ */
+export declare const consoleSink: <TLogObject = unknown>() => LoggerSink<TLogObject>;

package/dist/sinks/devnull-logger.d.ts

@@ -0,0 +1,8 @@
+import type { LoggerSink } from '#/types/logger-sink';
+/**
+ * Creates a sink that discards all logs (like `/dev/null`).
+ * Useful for benchmarking the logger overhead without I/O.
+ *
+ * @typeParam TLogObject - The shape of the objects this sink accepts.
+ */
+export declare const devNullSink: <TLogObject = unknown>() => LoggerSink<TLogObject>;

package/dist/sinks/file-logger.d.ts

@@ -0,0 +1,9 @@
+import type { LoggerSink } from '#/types/logger-sink';
+/**
+ * Creates a sink that appends JSON log entries to a file.
+ * Uses `Bun.FileSink` for efficient buffered appending (runs in the worker context).
+ *
+ * @typeParam TLogObject - The shape of the objects this sink accepts.
+ * @param path - The destination file path.
+ */
+export declare const fileSink: <TLogObject = unknown>(path: string) => LoggerSink<TLogObject>;

package/dist/types/log-levels.d.ts

@@ -0,0 +1 @@
+export type LogLevels = 'ERROR' | 'WARN' | 'INFO' | 'DEBUG' | 'LOG' | 'TRACE';

package/dist/types/logger-sink.d.ts

@@ -0,0 +1,36 @@
+import type { LogLevels } from './log-levels';
+/**
+ * A logging destination.
+ *
+ * This is the object a {@link SinkFactory} returns. The factory runs inside the
+ * logger worker, so the sink closes over its own state (file handles, buffers, …)
+ * instead of exposing it. All values the sink needs must be created **inside** the
+ * factory body — it cannot close over module-scoped imports (use dynamic `import()`
+ * or runtime globals such as `Bun` instead).
+ */
+export interface LoggerSink<TLogObject = unknown, TConfig = unknown> {
+    /** Optional configuration for the sink */
+    readonly config?: TConfig;
+    /**
+     * Logs a message with the sink's implementation.
+     *
+     * @param level - The log level at which the message should be logged.
+     * @param timestamp - The epoch timestamp (ms) at which the message was logged.
+     * @param object - The object to log.
+     *
+     * @returns A promise when the sink is asynchronous; it is awaited by {@link Logger.flush}.
+     */
+    log(level: LogLevels, timestamp: number, object: TLogObject): Promise<void> | void;
+    /**
+     * Flushes any buffered data to the underlying destination.
+     * Called by {@link Logger.flush}; implement it when your sink buffers writes
+     * (e.g. a file writer) and durability on flush matters.
+     */
+    flush?(): Promise<void> | void;
+    /**
+     * Closes the sink and releases its resources.
+     * Called when the logger is closing. Optional - implement this if your sink needs
+     * cleanup (e.g. closing file handles, database connections).
+     */
+    close?(): Promise<void> | void;
+}

package/dist/types/sink-bodies-intersection.d.ts

@@ -0,0 +1,2 @@
+import type { SinkBody } from './sink-body';
+export type SinkBodiesIntersection<TSinks, K extends keyof TSinks> = (K extends unknown ? (object: SinkBody<TSinks, K>) => void : never) extends (object: infer I) => void ? I : never;

package/dist/types/sink-body.d.ts

@@ -0,0 +1,2 @@
+import type { LoggerSink } from './logger-sink';
+export type SinkBody<TSink, Key extends keyof TSink> = TSink[Key] extends (...args: any[]) => LoggerSink<infer TBody> ? TBody : never;

package/dist/types/sink-factory.d.ts

@@ -0,0 +1,12 @@
+import type { LoggerSink } from './logger-sink';
+/**
+ * A factory that builds a {@link LoggerSink}.
+ *
+ * The factory is serialized and re-evaluated inside the logger worker, so its body
+ * must be self-contained: it can only rely on its arguments, runtime globals, and
+ * dynamic `import()` — never on module-scoped imports captured by closure.
+ *
+ * @typeParam TLogObject - The shape of the objects this sink accepts.
+ * @typeParam TArgs - The factory arguments forwarded from `registerSink`.
+ */
+export type SinkFactory<TLogObject = unknown, TArgs extends readonly unknown[] = readonly unknown[]> = (...args: TArgs) => LoggerSink<TLogObject>;

package/dist/types/sink-map.d.ts

@@ -0,0 +1,2 @@
+import type { LoggerSink } from './logger-sink';
+export type SinkMap = Record<string, (...args: any[]) => LoggerSink>;

package/dist/worker-logger.d.ts

@@ -0,0 +1 @@
+export declare const workerFunction: () => void;

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@dws-std/logger",
+	"version": "1.0.0",
+	"description": "Type-safe logging library for Bun, modular sink pattern, transform streams, and immutable API design.",
+	"keywords": [
+		"bun",
+		"dws",
+		"open-source",
+		"types",
+		"typescript",
+		"utilities"
+	],
+	"license": "MIT",
+	"author": "Dominus Web Services (DWS)",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Dominus-Web-Service/std",
+		"directory": "packages/logger"
+	},
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "bun builder.ts",
+		"docs": "bunx typedoc --tsconfig tsconfig.build.json",
+		"fmt:check": "oxfmt --check",
+		"fmt": "oxfmt",
+		"lint:fix": "oxlint --type-aware --type-check --fix ./src",
+		"lint:github": "oxlint --type-aware --type-check --format=github ./src",
+		"lint": "oxlint --type-aware --type-check ./src",
+		"test": "bun test --pass-with-no-tests --coverage"
+	},
+	"dependencies": {
+		"@dws-std/common": "workspace:^",
+		"@dws-std/error": "workspace:^"
+	},
+	"devDependencies": {
+		"@types/bun": "catalog:base",
+		"mitata": "^1.0.34",
+		"oxfmt": "catalog:base",
+		"oxlint": "catalog:base",
+		"oxlint-tsgolint": "catalog:base",
+		"pino": "^10.3.1",
+		"typescript": "catalog:base"
+	},
+	"peerDependencies": {
+		"@dws-std/common": "workspace:^",
+		"@dws-std/error": "workspace:^"
+	}
+}