@asaidimu/utils-logger 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saidimu
+
+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,267 @@
+# @asaidimu/utils-logger
+
+A robust, structured logging library for TypeScript/JavaScript applications. It provides a context-aware logger with support for multiple sinks (console, event bus, custom destinations), hierarchical child loggers, and advanced error formatting—all designed to simplify observability in complex systems.
+
+---
+
+## Features
+
+- **Structured Logging** – Logs are consistent objects with `level`, `event`, `timestamp`, `data`, and `context` fields.
+- **Log Levels** – `trace`, `debug`, `info`, `warn`, `error` with priority filtering.
+- **Context Propagation** – Attach contextual metadata to a logger; child loggers inherit and merge context.
+- **Pluggable Sinks** – Send logs to one or multiple destinations (console, event bus, files, etc.).
+- **Built‑in Sinks** – `ConsoleSink` (stdout/stderr) and `EventBusSink` (integrates with an event bus).
+- **Fuzz Logger** – Generate random logs for testing and performance benchmarking.
+- **Error‑Aware** – Automatically extracts structured fields from `SystemError` and plain `Error` objects.
+- **Type‑Safe** – Written in TypeScript with full type definitions included.
+
+---
+
+## Installation
+
+```bash
+npm install @asaidimu/utils-logger
+```
+
+> **Peer dependency**: `ws` (`^8.21.0`) is required if you use the `UnsecureWebSocketServerSink` with WebSocket‑based buses. Install it separately if needed.
+> **Peer dependency**: `@asaidimu/utils-events` (`^1.2.0`) is required if you use the `EventBusSink` Install it separately if needed.
+
+---
+
+## Quick Start
+
+```typescript
+import { Logger, ConsoleSink } from "@asaidimu/utils-logger";
+
+// Create a logger that writes to the console
+const logger = new Logger([new ConsoleSink()], {
+  app: "my-service",
+  environment: "development",
+});
+
+// Basic logging
+logger.info("user_logged_in", { userId: "123", ip: "192.168.1.1" });
+
+// Error logging
+try {
+  // ...
+} catch (err) {
+  logger.error("database_query_failed", err);
+}
+
+// Child logger with additional context
+const childLogger = logger.child({ requestId: "abc-123" });
+childLogger.debug("processing_payment", { amount: 99.99 });
+```
+
+---
+
+## Core Concepts
+
+### Logger
+
+The main entry point implementing the `SystemLogger` interface. It holds a set of sinks, a base context, and methods for each log level.
+
+### Sinks
+
+A sink is any object implementing the `LogSink` interface:
+
+```typescript
+interface LogSink {
+  write(record: SystemLog): void | Promise<void>;
+}
+```
+
+When a log is emitted, it is passed to **all** registered sinks concurrently. If a sink returns a `Promise`, it is awaited (with `Promise.all`) but errors are swallowed to prevent logging failures from crashing the application.
+
+### Context
+
+Context is an arbitrary object attached to every log record. It is useful for adding static metadata like service name, environment, or trace IDs. Child loggers merge new context onto the parent’s context.
+
+---
+
+## Built‑in Sinks
+
+### ConsoleSink
+
+Writes formatted log lines to `stdout` or `stderr`. It automatically detects the runtime:
+
+- In Node.js, uses `process.stdout.write` / `process.stderr.write`.
+- In browsers, falls back to `console.log`, `console.error`, etc.
+
+**Options**
+
+| Option    | Type                                     | Description                                                                                             |
+| --------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `pipeMap` | `Partial<Record<LogLevel, ConsolePipe>>` | Override the output stream for specific levels (default: `warn`/`error` → `stderr`, others → `stdout`). |
+| `format`  | `(record: SystemLog) => string`          | Custom string formatter. Default produces `[ISO timestamp] LEVEL event ctx=... data=...`.               |
+
+**Example**
+
+```typescript
+const consoleSink = new ConsoleSink({
+  pipeMap: { error: "stdout" }, // send errors to stdout
+  format: (r) => `[${r.level}] ${r.event}`,
+});
+```
+
+### EventBusSink
+
+Routes logs to an event bus, either statically or dynamically. This is useful for cross‑component communication, WebSocket broadcasts, or centralised log aggregation.
+
+**Requirements**
+
+- An event bus that implements the `EventBus<TEventMap>` interface (from `@asaidimu/utils-events`). The event map defines the allowed event names and their payload shapes.
+
+**Static Routing** – All logs go to a fixed event name.
+
+```typescript
+import { EventBusSink } from '@asaidimu/utils-logger';
+
+const eventBus = /* your event bus instance */;
+
+const sink = new EventBusSink(eventBus, {
+  event: 'system:log',          // static event name
+  map: (record) => ({           // optional mapping
+    level: record.level,
+    message: record.event,
+    timestamp: record.timestamp,
+    extra: record.data
+  })
+});
+```
+
+**Dynamic Routing** – Choose the event name per log record.
+
+```typescript
+const sink = new EventBusSink(eventBus, {
+  resolve: (record) => {
+    // Route based on log level or event name
+    return record.level === "error" ? "error:log" : "info:log";
+  },
+  map: (record, eventName) => ({
+    // eventName is the resolved name
+    severity: record.level,
+    details: record.data,
+  }),
+});
+```
+
+The sink guards against exceptions so that failures in event emission do not break the logging flow.
+
+---
+
+## Fuzz
+
+A helper class that generates random log entries at random intervals. Useful for load testing, demo environments, or stress‑testing your logging pipeline.
+
+```typescript
+import { Fuzz } from "@asaidimu/utils-logger";
+import { Logger, ConsoleSink } from "@asaidimu/utils-logger";
+
+const realLogger = new Logger([new ConsoleSink()]);
+const fuzz = new Fuzz(realLogger, {
+  minIntervalMs: 200,
+  maxIntervalMs: 1500,
+  allowedLevels: ["info", "warn", "error"],
+  eventRegistry: {
+    info: ["user_login", "order_placed", "payment_success"],
+    error: ["db_timeout", "stripe_failure"],
+  },
+});
+
+// Start emitting random logs every 200–1500ms
+fuzz.start();
+
+// Later, stop
+fuzz.stop();
+```
+
+**Options**
+
+| Option          | Type                                  | Default                                   | Description                                                                           |
+| --------------- | ------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- |
+| `minIntervalMs` | `number`                              | `100`                                     | Minimum delay between logs (ms).                                                      |
+| `maxIntervalMs` | `number`                              | `1000`                                    | Maximum delay between logs (ms).                                                      |
+| `allowedLevels` | `LogLevel[]`                          | `['trace','debug','info','warn','error']` | Which levels may be emitted.                                                          |
+| `eventRegistry` | `Partial<Record<LogLevel, string[]>>` | `{}`                                      | Custom event name pools per level. If empty, random hacker‑style names are generated. |
+
+---
+
+## API Reference
+
+### `SystemLogger` Interface
+
+| Method                                       | Description                                                                 |
+| -------------------------------------------- | --------------------------------------------------------------------------- |
+| `trace(event: string, data?: object): void`  | Log at `trace` level.                                                       |
+| `debug(event: string, data?: object): void`  | Log at `debug` level.                                                       |
+| `info(event: string, data?: object): void`   | Log at `info` level.                                                        |
+| `log(event: string, data?: object): void`    | Alias for `info`.                                                           |
+| `warn(event: string, data?: object): void`   | Log at `warn` level.                                                        |
+| `error(event: string, data?: unknown): void` | Log at `error` level. `data` can be an `Error` object (see Error handling). |
+| `write(record: SystemLog): void`             | Write a pre‑constructed `SystemLog` record directly.                        |
+| `child(context: object): SystemLogger`       | Create a child logger with additional context (merged over parent).         |
+
+### `Logger` Class
+
+The concrete implementation. Constructor:
+
+```typescript
+new Logger(sinks: LogSink[], context?: object)
+```
+
+All methods from `SystemLogger` are available.
+
+### `LogSink` Interface
+
+```typescript
+interface LogSink {
+  write(record: SystemLog): void | Promise<void>;
+}
+```
+
+Implement this to create custom sinks (e.g., file, HTTP, Sentry, etc.).
+
+### `SystemLog` Structure
+
+| Field       | Type       | Description                                          |
+| ----------- | ---------- | ---------------------------------------------------- |
+| `level`     | `LogLevel` | Severity level.                                      |
+| `event`     | `string`   | Distinct event name (e.g., `"user_login"`).          |
+| `data`      | `object`   | (Optional) Payload specific to the log.              |
+| `context`   | `object`   | (Optional) Static metadata from the logger instance. |
+| `timestamp` | `number`   | Unix timestamp in milliseconds (auto‑generated).     |
+
+### `LogLevel`
+
+```typescript
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+```
+
+Priority order (low to high): `trace` (10), `debug` (20), `info` (30), `warn` (40), `error` (50). The constant `LogLevelPriority` provides these numeric values.
+
+---
+
+## Error Handling
+
+When you pass an `Error` object (or any subclass) to `logger.error()`, the logger automatically extracts structured information:
+
+- For plain `Error`: it captures `name`, `message`, and `stack`.
+- For `SystemError` (from `@asaidimu/utils-error`): it additionally extracts `code`, `category`, `severity`, `path`, `operation`, `issues`, `httpStatus`, `action`, and `cause`.
+
+All extracted fields are placed under the `error` key in the log’s `data` property, ensuring consistent error reporting across your system.
+
+---
+
+## License
+
+MIT © [Saidimu](https://github.com/asaidimu)
+
+---
+
+## Contributing & Issues
+
+Found a bug or want to suggest an improvement? Please open an issue on the [GitHub repository](https://github.com/asaidimu/erp-utils/issues).
+
+For more details, visit the [homepage](https://github.com/asaidimu/erp-utils/tree/main/src/logger).

package/index.d.mts

@@ -0,0 +1,334 @@
+import { WebSocketServer } from 'ws';
+
+/**
+ * Represents the severity level of a system log entry.
+ * Levels are ordered by increasing severity: trace, debug, info, warn, error.
+ */
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+/**
+ * Defines a destination where system logs are outputted or processed.
+ * Custom sinks (e.g., File, Logstash, Sentry) must implement this interface.
+ */
+interface LogSink {
+    /**
+     * Dispatches a structured log entry to the underlying destination.
+     *
+     * @param record - The complete log object containing metadata and payload.
+     * @returns A void or Promise that resolves when the log has been safely handed off.
+     */
+    write(record: SystemLog): void | Promise<void>;
+}
+/**
+ * Structure representing a fully contextualized system log entry ready for sinking.
+ */
+interface SystemLog {
+    /** The severity level of the log. */
+    level: LogLevel;
+    /** A clear, human-readable string identifying the distinct event (e.g., "user_login_failed"). */
+    event: string;
+    /** Additional structured data specific to this log instantiation. */
+    data?: object;
+    /** Contextual data shared across the logger instance (e.g., traceIds, environment). */
+    context?: object;
+    /** Epoch timestamp in milliseconds denoting when the log event occurred. */
+    timestamp: number;
+}
+/**
+ * Primary logger interface providing level-specific log dispatching and context-chaining.
+ */
+interface SystemLogger {
+    /** Logs high-volume, extremely fine-grained diagnostic details. */
+    trace(event: string, data?: object): void;
+    /** Logs diagnostic information useful during local development or debugging. */
+    debug(event: string, data?: object): void;
+    /** Logs standard operational events that track the healthy flow of the system. */
+    info(event: string, data?: object): void;
+    /** Alias for the `info` logging method. */
+    log(event: string, data?: object): void;
+    /** Logs non-fatal operational anomalies or conditions that deserve attention. */
+    warn(event: string, data?: object): void;
+    /** Logs critical errors, failures, or exceptions preventing a transaction/process. */
+    error(event: string, data?: unknown): void;
+    /**
+     * Directly forwards a pre-constructed `SystemLog` record through the logger's pipeline.
+     * Combines instance context before outputting.
+     */
+    write(record: SystemLog): void;
+    /**
+     * Generates a new `SystemLogger` instance that shares the existing sinks and parent
+     * context, deeply merging the newly provided context on top.
+     *
+     * @param context - The metadata to append to all subsequent logs emitted by the child logger.
+     */
+    child(context: object): SystemLogger;
+}
+/**
+ * Numeric priority weights mapping to `LogLevel` values.
+ * Useful for filtering logs below a specific severity threshold.
+ */
+declare const LogLevelPriority: Record<LogLevel, number>;
+/**
+ * Concrete implementation of the `SystemLogger` interface.
+ * Handles active context-aggregation, standardized formatting of localized error payloads,
+ * and safe dispatch handling for downstream sinks.
+ */
+declare class Logger implements SystemLogger {
+    private context;
+    private sink;
+    /**
+     * Initializes a new instance of the core Logger wrapper.
+     * * @param sinks - An array of outputs where logs generated by this instance will be sent.
+     * @param context - Base contextual metadata to affix across all downstream log events.
+     */
+    constructor(sinks: Array<LogSink>, context?: object);
+    /**
+     * Safely updates or assigns the core logging sink.
+     * Used internally to re-attach existing sink structures to spawned child logger instances.
+     */
+    private setSink;
+    /**
+     * Extracts structural tracking fields from standard JavaScript errors and advanced domain `SystemError` objects.
+     * Ensures call-stacks and metadata parameters map clean object parameters without blowing up standard logging pipelines.
+     * * @param err - The Error object or descendant instance to format.
+     * @returns An object payload mapped under standard keys ready for insertion into a log.
+     */
+    private extractErrorData;
+    /**
+     * Core dispatcher compiling standard schema variables, timestamps, contexts,
+     * and payloads prior to writing to the underlying `LogSink`.
+     * * @internal
+     */
+    private emit;
+    trace(event: string, data?: object): void;
+    debug(event: string, data?: object): void;
+    info(event: string, data?: object): void;
+    log(event: string, data?: object): void;
+    warn(event: string, data?: object): void;
+    error(event: string, data?: unknown): void;
+    /**
+     * Writes an externally built log record into the logging framework sink.
+     * Merges local logger metadata onto incoming payloads with priority leaning toward overriding parameters.
+     */
+    write(record: SystemLog): void;
+    /**
+     * Spawns a child logger instance carrying over pre-defined context parameters.
+     * Context configurations defined down-stream overwrite conflicting identifiers.
+     */
+    child(context: object): SystemLogger;
+}
+
+/** Standard system descriptor streams for console outputs. */
+type ConsolePipe = "stdout" | "stderr";
+/** Configuration options modifying behavior of the `ConsoleSink`. */
+interface ConsoleSinkOptions {
+    /** Optional override mapping log levels to specific output pipes (`stdout` or `stderr`). */
+    pipeMap?: Partial<Record<LogLevel, ConsolePipe>>;
+    /** Custom transformation callback converting a `SystemLog` payload into a printable string string. */
+    format?: (record: SystemLog) => string;
+}
+/**
+ * A `LogSink` implementation that writes formatted log strings to terminal stdout/stderr channels.
+ * Automatically switches between runtime capabilities (Node.js `process.stdout` or generic global `console`).
+ */
+declare class ConsoleSink implements LogSink {
+    private pipeMap;
+    private format;
+    /**
+     * Initializes a new instance of the `ConsoleSink`.
+     * * @param options - Configuration definitions for custom formats and piping targets.
+     */
+    constructor(options?: ConsoleSinkOptions);
+    /**
+     * Processes a log record and flushes it immediately to the runtime stream.
+     * Non-stringifiable context or data entries will fallback to standard JSON representations.
+     */
+    write(record: SystemLog): void;
+}
+
+/**
+ * Interface defining the shape of the EventBus.
+ * @template TEventMap - A record mapping event names to their respective payload types.
+ */
+interface EventBus<TEventMap extends Record<string, any>> {
+    /**
+     * Subscribes to a specific event by name.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @param options -  Extra options to determine the behaviour of the
+     * subscription
+     * @returns A function to unsubscribe from the event.
+     */
+    subscribe: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions) => () => void;
+    /**
+     * Subscribes to an event and automatically unsubscribes after it fires once.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to cancel the one-shot subscription before it fires.
+     */
+    once: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions) => () => void;
+    /**
+     * Emits an event with a payload to all subscribed listeners.
+     * @param event - An object containing the event name and payload.
+     */
+    emit: <TEventName extends keyof TEventMap>(event: {
+        name: TEventName;
+        payload: TEventMap[TEventName];
+    }) => void;
+    /**
+     * Retrieves metrics about event bus usage.
+     * @returns An object containing various metrics.
+     */
+    metrics: () => EventMetrics;
+    /**
+     * Clears all subscriptions and resets metrics.
+     *
+     * After calling `clear()`, the bus is fully reset and can be reused
+     * cross-tab communication is re-established if it was previously enabled.
+     *
+     * @param options - Optional configuration object.
+     * @param options.permanent - If `true`, the bus becomes permanently unusable after clearing.
+     *                            Defaults to `false`.
+     * @returns {void}
+     */
+    clear: (options?: {
+        permanent?: boolean;
+    }) => void;
+}
+/**
+ * Interface defining the metrics tracked by the EventBus.
+ */
+interface EventMetrics {
+    /** Total number of events emitted (both sync and deferred paths). */
+    totalEvents: number;
+    /** Number of active subscriptions across all event names. */
+    activeSubscriptions: number;
+    /** Map of event names to their emission counts. */
+    eventCounts: Map<string, number>;
+    /** Average duration of event dispatch in milliseconds. */
+    averageEmitDuration: number;
+}
+interface SubscribeOptions {
+    /**
+     * Debounce delay in milliseconds. When multiple events arrive in quick
+     * succession, the callback runs only after the quiet period ends, using the
+     * latest payload. Default = no debouncing.
+     */
+    debounce?: number;
+}
+
+/**
+ * Configuration options for the EventBusSink when routing all logs to a single,
+ * static event channel on the EventBus.
+ */
+interface StaticRouteOptions<TEventMap extends Record<string, any>, TEventName extends keyof TEventMap> {
+    /** The fixed event name on the bus where all logs will be published. */
+    event: TEventName;
+    /** * Transforms the `SystemLog` into the format expected by the target event's payload.
+     * If omitted, the raw `SystemLog` is passed (requires type compatibility).
+     */
+    map?: (record: SystemLog) => TEventMap[TEventName];
+}
+/**
+ * Configuration options for the EventBusSink when routing logs dynamically
+ * across various event channels based on log record properties.
+ */
+interface DynamicRouteOptions<TEventMap extends Record<string, any>> {
+    /** A resolver callback that determines which event channel on the bus to target for a given log. */
+    resolve: (record: SystemLog) => keyof TEventMap;
+    /** * Transforms the `SystemLog` into the payload format expected by the resolved event channel.
+     * If omitted, the raw `SystemLog` is forwarded.
+     */
+    map?: (record: SystemLog, eventName: keyof TEventMap) => TEventMap[keyof TEventMap];
+}
+/**
+ * A `LogSink` implementation that translates and forwards `SystemLog` records
+ * into an application-wide or cross-tab `EventBus`.
+ * * @template TEventMap - The schema defining available event names and payloads on the target bus.
+ */
+declare class EventBusSink<TEventMap extends Record<string, any>> implements LogSink {
+    private eventBus;
+    private resolveEventName;
+    private mapPayload;
+    /**
+     * Initializes the EventBusSink using a static event channel definition.
+     */
+    constructor(eventBus: EventBus<TEventMap>, options: StaticRouteOptions<TEventMap, keyof TEventMap>);
+    /**
+     * Initializes the EventBusSink using a dynamic event resolution function.
+     */
+    constructor(eventBus: EventBus<TEventMap>, options: DynamicRouteOptions<TEventMap>);
+    /**
+     * Dispatches the incoming system log to the configured EventBus channel.
+     * Wraps operations in a guard block to ensure event bus payload mapping anomalies
+     * or downstream listener execution crashes do not disrupt the critical logger pathway.
+     * * @param record - The structural log entry processed by the parent logger.
+     */
+    write(record: SystemLog): void;
+}
+
+type FuzzEventRegistry = Record<LogLevel, string[]>;
+interface FakerFuzzOptions {
+    minIntervalMs?: number;
+    maxIntervalMs?: number;
+    allowedLevels?: LogLevel[];
+    eventRegistry?: Partial<FuzzEventRegistry>;
+}
+declare class Fuzz {
+    private logger;
+    private minIntervalMs;
+    private maxIntervalMs;
+    private allowedLevels;
+    private eventRegistry;
+    private timer;
+    private isRunning;
+    constructor(targetLogger: SystemLogger, options?: FakerFuzzOptions);
+    start(): void;
+    stop(): void;
+    private scheduleNextTick;
+    private getEventName;
+    private emitRandomLog;
+}
+
+/**
+ * Configuration options for the UnsecureWebSocketServerSink.
+ */
+interface UnsecureWebSocketSinkOptions {
+    /**
+     * An optional filter function to determine if a log should be broadcasted.
+     */
+    filter?: (record: SystemLog) => boolean;
+    /**
+     * Custom serialization function to transform the log before wire transmission.
+     * Defaults to standard `JSON.stringify`.
+     */
+    serialize?: (record: SystemLog) => string;
+}
+/**
+ * A `LogSink` implementation that broadcasts structured system logs in real-time
+ * to all connected WebSocket clients without verifying credentials.
+ * * @deprecated **SECURITY WARNING:** This sink performs no authentication or token validation.
+ * Do not expose this server to the public internet. Use exclusively for local development
+ * or behind heavily isolated VPC/internal network infrastructure.
+ */
+declare class UnsecureWebSocketServerSink implements LogSink {
+    private wss;
+    private filter?;
+    private serialize;
+    /**
+     * @param wss - An instantiated and running WebSocketServer instance.
+     * @param options - Configuration options for filtering and formatting the socket stream.
+     */
+    constructor(wss: WebSocketServer, options?: UnsecureWebSocketSinkOptions);
+    /**
+     * Broadcasts the incoming system log to all open, unauthenticated WebSocket clients.
+     * * @param record - The structural log entry processed by the parent logger.
+     */
+    write(record: SystemLog): void;
+    private handleClientError;
+    /**
+     * Periodically checks for and prunes "ghost" connections.
+     */
+    private initializeHeartbeat;
+}
+
+export { type ConsolePipe, ConsoleSink, type ConsoleSinkOptions, type DynamicRouteOptions, EventBusSink, type FakerFuzzOptions, Fuzz, type FuzzEventRegistry, type LogLevel, LogLevelPriority, type LogSink, Logger, type StaticRouteOptions, type SystemLog, type SystemLogger, UnsecureWebSocketServerSink, type UnsecureWebSocketSinkOptions };