@eventuras/logger 0.7.0

package/README.md

@@ -0,0 +1,309 @@
+# @eventuras/logger
+
+A structured logging library with pluggable transports and optional OpenTelemetry integration. Works in Node.js and browser environments.
+
+## Features
+
+- 🎯 **Scoped loggers** — Create instances with persistent context and namespace
+- 🔌 **Pluggable transports** — Use Pino (default), console, or bring your own
+- 🔒 **Auto-redaction** — Protect sensitive fields in log output
+- 📊 **Log levels** — Control verbosity per logger or globally
+- 🔍 **Correlation IDs** — Track requests across services
+- 🌐 **OpenTelemetry** — Optional integration for any OTel-compatible backend
+- 🌍 **Cross-runtime** — Works in Node.js, browsers, and edge runtimes
+
+## Installation
+
+```bash
+pnpm add @eventuras/logger
+```
+
+## Quick Start
+
+### Scoped Logger (recommended)
+
+```typescript
+import { Logger } from "@eventuras/logger";
+
+const logger = Logger.create({
+  namespace: "web:admin:events",
+  context: { module: "EventEditor" },
+});
+
+logger.info({ eventId: 42 }, "Event updated");
+logger.error({ error }, "Failed to save event");
+```
+
+### Static Methods (one-off logs)
+
+```typescript
+import { Logger } from "@eventuras/logger";
+
+Logger.info("Server started");
+Logger.warn({ memoryUsage: "85%" }, "Memory usage high");
+Logger.error({ error }, "Unhandled exception");
+```
+
+## Log Levels
+
+From most to least verbose:
+
+| Level   | Value | Use case                     |
+| ------- | ----- | ---------------------------- |
+| `trace` | 10    | Fine-grained debugging       |
+| `debug` | 20    | Development debugging        |
+| `info`  | 30    | General events **(default)** |
+| `warn`  | 40    | Warnings                     |
+| `error` | 50    | Errors                       |
+| `fatal` | 60    | Critical/shutdown errors     |
+
+## Configuration
+
+Configure the logger once at application startup:
+
+```typescript
+import { Logger } from "@eventuras/logger";
+
+Logger.configure({
+  level: "debug",
+  prettyPrint: process.env.NODE_ENV === "development",
+  redact: ["password", "token", "apiKey", "authorization", "secret"],
+  destination: "/var/log/app.log", // Optional file output
+});
+```
+
+### Environment Variables
+
+```bash
+LOG_LEVEL=debug       # Set global log level
+NODE_ENV=development  # Enables pretty printing
+```
+
+## Transports
+
+The library uses a pluggable transport system. A transport implements the `LogTransport` interface:
+
+```typescript
+interface LogTransport {
+  log(level: LogLevel, data: Record<string, unknown>, msg?: string): void;
+  child(bindings: Record<string, unknown>): LogTransport;
+  flush?(): Promise<void>;
+  shutdown?(): Promise<void>;
+}
+```
+
+### PinoTransport (default in Node.js)
+
+[Pino](https://getpino.io) is included as a dependency and used automatically in Node.js environments. In browser/edge runtimes, `ConsoleTransport` is used as the default instead.
+
+```typescript
+import { Logger, PinoTransport } from "@eventuras/logger";
+
+// Explicit Pino configuration
+Logger.configure({
+  transport: new PinoTransport({
+    level: "debug",
+    prettyPrint: true,
+    redact: ["password", "secret"],
+  }),
+});
+```
+
+### ConsoleTransport
+
+A lightweight transport using native `console` methods. Automatically selected as the default in browser and edge runtimes. Also useful for testing:
+
+```typescript
+import { Logger, ConsoleTransport } from "@eventuras/logger";
+
+Logger.configure({
+  transport: new ConsoleTransport(),
+});
+```
+
+### Custom Transport
+
+Implement the `LogTransport` interface for any logging backend:
+
+```typescript
+import type { LogTransport, LogLevel } from "@eventuras/logger";
+
+class DatadogTransport implements LogTransport {
+  log(level: LogLevel, data: Record<string, unknown>, msg?: string) {
+    // Send to Datadog, Winston, Bunyan, or any backend
+  }
+
+  child(bindings: Record<string, unknown>): LogTransport {
+    // Return a new transport with merged bindings
+    return new DatadogTransport({ ...this.config, bindings });
+  }
+}
+
+Logger.configure({ transport: new DatadogTransport() });
+```
+
+## Auto-Redaction
+
+Sensitive fields are automatically redacted:
+
+```typescript
+logger.info(
+  {
+    username: "john",
+    password: "secret123", // → '[REDACTED]'
+    apiKey: "key_123", // → '[REDACTED]'
+  },
+  "User login",
+);
+```
+
+Default redacted paths: `password`, `token`, `apiKey`, `authorization`, `secret`.
+
+Configure additional paths via `Logger.configure({ redact: [...] })`.
+
+## HTTP Header Redaction
+
+Utility for redacting sensitive HTTP headers:
+
+```typescript
+import { redactHeaders } from "@eventuras/logger";
+
+const safe = redactHeaders(request.headers);
+logger.info({ headers: safe }, "Incoming request");
+```
+
+Redacts `authorization`, `cookie`, `set-cookie`, `x-api-key`, `x-auth-token`, and `proxy-authorization`.
+
+## OpenTelemetry Integration
+
+Send logs to any OTel-compatible backend (Sentry, Grafana, Jaeger, etc.) without vendor lock-in.
+
+### Install OTel Packages
+
+```bash
+pnpm add @opentelemetry/api @opentelemetry/api-logs @opentelemetry/sdk-logs \
+  @opentelemetry/instrumentation-pino @opentelemetry/exporter-logs-otlp-http
+```
+
+These are optional peer dependencies — the library works fine without them.
+
+### Setup
+
+```typescript
+import { setupOpenTelemetryLogger } from "@eventuras/logger/opentelemetry";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
+
+setupOpenTelemetryLogger({
+  serviceName: "my-app",
+  logRecordProcessor: new BatchLogRecordProcessor(
+    new OTLPLogExporter({
+      url: process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT,
+    }),
+  ),
+});
+```
+
+### Shutdown
+
+```typescript
+import { shutdownOpenTelemetryLogger } from "@eventuras/logger/opentelemetry";
+
+process.on("SIGTERM", async () => {
+  await shutdownOpenTelemetryLogger();
+  process.exit(0);
+});
+```
+
+### Environment Variables
+
+```bash
+OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://...
+OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-api-key=YOUR_KEY
+OTEL_SERVICE_NAME=my-app
+```
+
+## Examples
+
+### API Route Handler
+
+```typescript
+import { Logger } from "@eventuras/logger";
+
+export async function POST(req: Request) {
+  const logger = Logger.create({
+    namespace: "events-api",
+    correlationId: req.headers.get("x-correlation-id") || crypto.randomUUID(),
+  });
+
+  try {
+    const data = await req.json();
+    logger.info("Creating event");
+
+    const result = await createEvent(data);
+    logger.info({ eventId: result.id }, "Event created");
+
+    return Response.json(result);
+  } catch (error) {
+    logger.error({ error }, "Failed to create event");
+    return Response.json({ error: "Internal server error" }, { status: 500 });
+  }
+}
+```
+
+### Server Action
+
+```typescript
+"use server";
+
+import { Logger } from "@eventuras/logger";
+
+const logger = Logger.create({ namespace: "web:admin:collections" });
+
+export async function updateCollection(data: CollectionDto) {
+  logger.info({ collectionId: data.id }, "Updating collection");
+
+  try {
+    const result = await api.put(data);
+    logger.info({ collectionId: data.id }, "Collection updated");
+    return { success: true, data: result };
+  } catch (error) {
+    logger.error({ error, collectionId: data.id }, "Failed to update");
+    return { success: false, error: "Update failed" };
+  }
+}
+```
+
+## TypeScript
+
+All types are exported:
+
+```typescript
+import type {
+  LogTransport,
+  LogLevel,
+  LoggerOptions,
+  LoggerConfig,
+  ErrorLoggerOptions,
+} from "@eventuras/logger";
+```
+
+## Subpath Exports
+
+| Import path                       | Contents                                                        | Environment |
+| --------------------------------- | --------------------------------------------------------------- | ----------- |
+| `@eventuras/logger`               | Logger, types, PinoTransport, ConsoleTransport, httpLogger      | Universal   |
+| `@eventuras/logger/node`          | `formatLogLine`, `createPrettyStream` (depends on `node:stream`) | Node.js     |
+| `@eventuras/logger/opentelemetry` | `setupOpenTelemetryLogger`, `shutdownOpenTelemetryLogger`        | Node.js     |
+
+### Node-only Pretty-print Utilities
+
+The pretty-print formatter and stream are available via a separate entry point to avoid pulling `node:stream` into browser bundles:
+
+```typescript
+import { createPrettyStream, formatLogLine } from "@eventuras/logger/node";
+```
+
+## License
+
+Apache-2.0

package/dist/Logger.d.ts

@@ -0,0 +1,105 @@
+import { ErrorLoggerOptions, LoggerConfig, LoggerOptions, LogTransport } from './types';
+export declare class Logger {
+    private static transport;
+    private static config;
+    private readonly options;
+    private readonly childTransport?;
+    private constructor();
+    /**
+     * Configure global logger settings. Call once at application startup.
+     *
+     * Supply a custom `transport` to replace the default Pino backend,
+     * or omit it to keep PinoTransport with the provided options.
+     *
+     * @example
+     * Logger.configure({ level: 'debug', redact: ['password', 'apiKey'] });
+     *
+     * @example
+     * import { ConsoleTransport } from '@eventuras/logger';
+     * Logger.configure({ transport: new ConsoleTransport() });
+     */
+    static configure(config: Partial<LoggerConfig>): void;
+    /**
+     * Get the active transport for advanced integrations.
+     *
+     * If you need access to the underlying Pino instance (e.g. for OTel
+     * instrumentation), check `transport instanceof PinoTransport` and
+     * access `.pino` on it.
+     */
+    static getTransport(): LogTransport;
+    /**
+     * @deprecated Use `Logger.getTransport()` instead. If you need the raw
+     * Pino instance, cast the transport: `(Logger.getTransport() as PinoTransport).pino`
+     */
+    static getPinoInstance(): import('pino').Logger;
+    /**
+     * Normalize arguments for static log methods.
+     * Supports both `Logger.info('msg')` and `Logger.info({ namespace: 'x' }, 'msg')`.
+     */
+    private static normalizeArgs;
+    private static isDevelopment;
+    private static formatError;
+    private static buildLogData;
+    private static staticLog;
+    private static staticErrorLog;
+    /** Log at info level with options and message(s). */
+    static info(options: LoggerOptions, ...msg: unknown[]): void;
+    /** Log at info level with just a message string. */
+    static info(msg: string, ...args: unknown[]): void;
+    /** Log at debug level with options and message(s). */
+    static debug(options: LoggerOptions, ...msg: unknown[]): void;
+    /** Log at debug level with just a message string. */
+    static debug(msg: string, ...args: unknown[]): void;
+    /** Log at trace level with options and message(s). */
+    static trace(options: LoggerOptions, ...msg: unknown[]): void;
+    /** Log at trace level with just a message string. */
+    static trace(msg: string, ...args: unknown[]): void;
+    /** Log at warn level with options and message(s). */
+    static warn(options: LoggerOptions, ...msg: unknown[]): void;
+    /** Log at warn level with just a message string. */
+    static warn(msg: string, ...args: unknown[]): void;
+    /** Log at error level with options and message(s). */
+    static error(options: ErrorLoggerOptions, ...msg: unknown[]): void;
+    /** Log at error level with just a message string. */
+    static error(msg: string, ...args: unknown[]): void;
+    /** Log at fatal level with options and message(s). */
+    static fatal(options: ErrorLoggerOptions, ...msg: unknown[]): void;
+    /** Log at fatal level with just a message string. */
+    static fatal(msg: string, ...args: unknown[]): void;
+    private static rebindStaticMethods;
+    /**
+     * Create a scoped logger instance with predefined options.
+     *
+     * @example
+     * const logger = Logger.create({ namespace: 'CollectionEditor' });
+     * logger.info('Something happened');
+     *
+     * @example
+     * const logger = Logger.create({
+     *   namespace: 'API',
+     *   context: { userId: 123 },
+     *   correlationId: req.headers['x-correlation-id'],
+     * });
+     * logger.info({ eventId: 789 }, 'Event added');
+     */
+    static create(options?: LoggerOptions): Logger;
+    private logInstance;
+    /** Log at `trace` level. Pass a string or `{ data }` with an optional message. */
+    trace(data?: Record<string, unknown> | string, msg?: string): void;
+    /** Log at `debug` level. */
+    debug(data?: Record<string, unknown> | string, msg?: string): void;
+    /** Log at `info` level. */
+    info(data?: Record<string, unknown> | string, msg?: string): void;
+    /** Log at `warn` level. */
+    warn(data?: Record<string, unknown> | string, msg?: string): void;
+    /**
+     * Log at `error` level. Accepts an `Error` instance, a data object, or a plain string.
+     * Error instances are serialized automatically.
+     */
+    error(errorOrData?: unknown, msg?: string): void;
+    /**
+     * Log at `fatal` level. Same signature as `error()` but signals a critical/shutdown failure.
+     */
+    fatal(errorOrData?: unknown, msg?: string): void;
+}
+//# sourceMappingURL=Logger.d.ts.map

package/dist/Logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../src/Logger.ts"],"names":[],"mappings":"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"}

package/dist/__vite-browser-external-pQ4XsTOI.js

@@ -0,0 +1,7 @@
+import { t as e } from "./chunk-NnHqS4_Y.js";
+//#region __vite-browser-external
+var t = /* @__PURE__ */ e(((e, t) => {
+	t.exports = {};
+}));
+//#endregion
+export { t };

package/dist/chunk-NnHqS4_Y.js

@@ -0,0 +1,20 @@
+//#region \0rolldown/runtime.js
+var e = Object.create, t = Object.defineProperty, n = Object.getOwnPropertyDescriptor, r = Object.getOwnPropertyNames, i = Object.getPrototypeOf, a = Object.prototype.hasOwnProperty, o = (e, t) => () => (e && (t = e(e = 0)), t), s = (e, t) => () => (t || e((t = { exports: {} }).exports, t), t.exports), c = (e, n) => {
+	let r = {};
+	for (var i in e) t(r, i, {
+		get: e[i],
+		enumerable: !0
+	});
+	return n || t(r, Symbol.toStringTag, { value: "Module" }), r;
+}, l = (e, i, o, s) => {
+	if (i && typeof i == "object" || typeof i == "function") for (var c = r(i), l = 0, u = c.length, d; l < u; l++) d = c[l], !a.call(e, d) && d !== o && t(e, d, {
+		get: ((e) => i[e]).bind(null, d),
+		enumerable: !(s = n(i, d)) || s.enumerable
+	});
+	return e;
+}, u = (n, r, a) => (a = n == null ? {} : e(i(n)), l(r || !n || !n.__esModule ? t(a, "default", {
+	value: n,
+	enumerable: !0
+}) : a, n)), d = (e) => a.call(e, "module.exports") ? e["module.exports"] : l(t({}, "__esModule", { value: !0 }), e);
+//#endregion
+export { u as a, d as i, o as n, c as r, s as t };