@asaidimu/utils-logger 1.0.0

package/index.d.ts

@@ -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 };