@rawnodes/logger 2.8.0 → 2.10.0

package/dist/index.d.ts

@@ -1,222 +1,7 @@
+import { L as LoggerContext, a as LoggerConfig, b as LevelOverrideMatch, c as LogLevel, d as LevelOverride, M as Meta, D as DiscordConfig, T as TelegramConfig, C as CloudWatchConfig, e as MaskReplacer, Z as ZohoCliqConfig, f as CallerConfig, g as CallerInfo, h as LogFormat, i as LevelRule, j as ConsoleConfig, F as FileConfig, H as HttpTransportBaseConfig, k as LevelConfigObject, l as LevelConfig, R as RelayConfig, A as AutoShutdownConfig, m as LogStreamPattern, n as LogStreamPatternConfig, o as LogStreamTemplateConfig, p as LogStreamName } from './types-lfJLhC8J.js';
+export { q as LOG_LEVELS, x as MaskSecretsOptions, t as ZohoCliqBotConfig, s as assertLogLevel, v as createMasker, r as isValidLogLevel, w as maskReplacer, u as maskSecrets } from './types-lfJLhC8J.js';
 import { z } from 'zod';
 
-declare const LOG_LEVELS: {
-    readonly off: -1;
-    readonly error: 0;
-    readonly warn: 1;
-    readonly info: 2;
-    readonly http: 3;
-    readonly verbose: 4;
-    readonly debug: 5;
-    readonly silly: 6;
-};
-type LogLevel = keyof typeof LOG_LEVELS;
-declare function isValidLogLevel(level: string): level is LogLevel;
-declare function assertLogLevel(level: string): asserts level is LogLevel;
-type LogFormat = 'json' | 'plain' | 'logfmt' | 'simple';
-interface LevelRule {
-    match: Record<string, unknown> & {
-        context?: string;
-    };
-    level: LogLevel;
-}
-interface ConsoleConfig {
-    format: LogFormat;
-    level?: LogLevel;
-    rules?: LevelRule[];
-}
-interface FileConfig {
-    format: LogFormat;
-    level?: LogLevel;
-    rules?: LevelRule[];
-    dirname: string;
-    filename: string;
-    datePattern?: string;
-    interval?: string;
-    zippedArchive?: boolean;
-    maxSize?: string;
-    maxFiles?: string;
-}
-interface HttpTransportBaseConfig {
-    level?: LogLevel;
-    rules?: LevelRule[];
-    batchSize?: number;
-    flushInterval?: number;
-    maxRetries?: number;
-    retryDelay?: number;
-    /**
-     * Maximum number of messages the in-memory queue will hold before dropping.
-     * Provides a hard upper bound on memory usage when a transport is degraded
-     * or offline — without this, a failing transport + steady log volume grows
-     * the queue until OOM. Default: unbounded.
-     *
-     * Recommended for production: `10_000` — enough to absorb transient blips,
-     * small enough to avoid runaway memory.
-     */
-    maxQueueSize?: number;
-    /**
-     * Policy applied when the queue is full.
-     * - `'drop-oldest'` (default): prefers keeping recent events — during an
-     *   outage old logs are usually stale.
-     * - `'drop-newest'`: prefers preserving historical context — useful if you
-     *   care more about the events leading up to the outage than the noise
-     *   happening during it.
-     */
-    dropPolicy?: 'drop-oldest' | 'drop-newest';
-    /**
-     * Called when messages are dropped due to queue overflow. Receives only the
-     * messages that were discarded. If not provided, drops are silent.
-     *
-     * Callback MUST NOT throw; if it does, the exception is swallowed.
-     */
-    onDrop?: (droppedMessages: unknown[]) => void;
-    /**
-     * Called when a batch fails after all retries and messages are dropped.
-     * If not provided, the error is logged to stderr.
-     *
-     * The callback MUST NOT throw; if it does, the failure is swallowed and a
-     * stderr fallback is used. This is intentional — a logger must never
-     * propagate its own transport errors back into the host application.
-     */
-    onError?: (error: Error, droppedMessages: unknown[]) => void;
-    /**
-     * Timeout in milliseconds for a single outbound HTTP request. Default:
-     * `10_000`. Applies to Discord/Telegram `fetch`. CloudWatch uses the AWS
-     * SDK's own timeout configuration.
-     */
-    requestTimeout?: number;
-}
-interface DiscordConfig extends HttpTransportBaseConfig {
-    webhookUrl: string;
-    format?: 'embed' | 'markdown';
-    username?: string;
-    avatarUrl?: string;
-    embedColors?: Partial<Record<LogLevel, number>>;
-    includeTimestamp?: boolean;
-    includeMeta?: boolean;
-    maxEmbedFields?: number;
-}
-interface TelegramConfig extends HttpTransportBaseConfig {
-    botToken: string;
-    chatId: string | number;
-    parseMode?: 'Markdown' | 'MarkdownV2' | 'HTML';
-    disableNotification?: boolean;
-    threadId?: number;
-    replyToMessageId?: number;
-}
-interface ZohoCliqBotConfig {
-    /** Bot display name (shown in the channel). */
-    name: string;
-    /** Optional bot avatar URL. */
-    image?: string;
-}
-interface ZohoCliqConfig extends HttpTransportBaseConfig {
-    /**
-     * Incoming webhook URL. If provided, `companyId`/`channel`/`region` are
-     * ignored and this URL is used as-is (with `zapikey` appended as query).
-     */
-    webhookUrl?: string;
-    /** Zoho Cliq company/org ID. Required unless `webhookUrl` is set. */
-    companyId?: string;
-    /** Target channel name (the `channelsbyname` API segment). Required unless `webhookUrl` is set. */
-    channel?: string;
-    /** Zoho region/TLD: 'eu' | 'com' | 'in' | etc. Default: 'eu'. */
-    region?: string;
-    /** Zoho API key (zapikey). Required. */
-    apiKey: string;
-    /** If true (default), message is posted as a broadcast so all members are notified. */
-    broadcast?: boolean;
-    /** Post as a custom bot instead of the default user. */
-    bot?: ZohoCliqBotConfig;
-    /** Include ISO timestamp in each formatted message. Default: true. */
-    includeTimestamp?: boolean;
-    /** Include meta as a fenced code block. Default: true. */
-    includeMeta?: boolean;
-}
-type LogStreamPattern = 'hostname' | 'hostname-date' | 'hostname-uuid' | 'date' | 'uuid';
-interface LogStreamPatternConfig {
-    pattern: LogStreamPattern;
-}
-interface LogStreamTemplateConfig {
-    /** Custom template with variables: {hostname}, {date}, {datetime}, {uuid}, {pid}, {env} */
-    template: string;
-}
-type LogStreamName = string | LogStreamPatternConfig | LogStreamTemplateConfig;
-interface RelayConfig {
-    /** URL of the relay API (e.g., https://relay.example.com) */
-    apiUrl: string;
-    /** Authentication token for the relay server */
-    token: string;
-    /** Polling interval in ms (default: 30000) */
-    pollInterval?: number;
-    /** Ring buffer capacity - max logs held during reconnect (default: 1000) */
-    bufferSize?: number;
-    /** WebSocket reconnect base delay in ms (default: 1000) */
-    reconnectDelay?: number;
-    /** Max reconnect delay in ms (default: 30000) */
-    maxReconnectDelay?: number;
-}
-interface CloudWatchConfig extends HttpTransportBaseConfig {
-    logGroupName: string;
-    /** Log stream name - string, pattern config, or template config. Defaults to hostname pattern */
-    logStreamName?: LogStreamName;
-    region: string;
-    accessKeyId: string;
-    secretAccessKey: string;
-    createLogGroup?: boolean;
-    createLogStream?: boolean;
-}
-interface LevelConfigObject {
-    default: LogLevel;
-    rules?: LevelRule[];
-}
-type LevelConfig = LogLevel | LevelConfigObject;
-interface CallerConfig {
-    /** Stack depth to capture (default: 1). Higher values trace further up the call stack */
-    depth?: number;
-    /** Include full file path (default: false). If false, shows relative or basename only */
-    fullPath?: boolean;
-}
-interface CallerInfo {
-    file: string;
-    line: number;
-    column?: number;
-    function?: string;
-}
-interface AutoShutdownConfig {
-    /** Timeout in ms before forcing exit (default: 5000) */
-    timeout?: number;
-    /** Custom signals to handle (default: ['SIGTERM', 'SIGINT']) */
-    signals?: NodeJS.Signals[];
-}
-interface LoggerConfig {
-    level: LevelConfig;
-    console: ConsoleConfig;
-    file?: FileConfig;
-    discord?: DiscordConfig | DiscordConfig[];
-    telegram?: TelegramConfig | TelegramConfig[];
-    cloudwatch?: CloudWatchConfig | CloudWatchConfig[];
-    zohoCliq?: ZohoCliqConfig | ZohoCliqConfig[];
-    /** Relay transport config — streams logs to a remote server via WebSocket (runs in worker thread) */
-    relay?: RelayConfig;
-    /** Enable caller info (file:line) in logs. Pass true for defaults or CallerConfig for options */
-    caller?: boolean | CallerConfig;
-    /** Hostname to include in all log entries. Defaults to os.hostname() if not specified */
-    hostname?: string;
-    /** Auto-register graceful shutdown handlers. Pass true for defaults or config object */
-    autoShutdown?: boolean | AutoShutdownConfig;
-}
-type LoggerContext = Record<string, unknown>;
-type LevelOverrideMatch<TContext extends LoggerContext> = Partial<TContext> & {
-    context?: string;
-};
-interface LevelOverride<TContext extends LoggerContext> {
-    match: LevelOverrideMatch<TContext>;
-    level: LogLevel;
-    readonly?: boolean;
-}
-type Meta = object | (() => object);
-
 declare class LoggerStore<TContext extends LoggerContext = LoggerContext> {
     private storage;
     getStore(): TContext | undefined;
@@ -365,10 +150,19 @@ interface BaseHttpTransportOptions {
      * back into the host application.
      */
     onError?: (error: Error, droppedMessages: BufferedMessage[]) => void;
+    /**
+     * If provided, applied to `meta` once per message in `transformMessage`. Used
+     * by transports that build payloads via `Object.entries(meta)` iteration
+     * (Discord/Telegram/Zoho), where a JSON.stringify replacer can't reach the
+     * top-level key. CloudWatch passes `undefined` here and uses a replacer in
+     * its own `sendBatch` instead.
+     */
+    masker?: (value: unknown) => unknown;
 }
 declare abstract class BaseHttpTransport {
     protected buffer: MessageBuffer;
     private onErrorCallback?;
+    private masker?;
     constructor(opts?: BaseHttpTransportOptions);
     log(info: Record<string, unknown>, callback: () => void): void;
     /**
@@ -394,7 +188,7 @@ declare function matchesContext(storeContext: LoggerContext | undefined, loggerC
 declare class DiscordTransport extends BaseHttpTransport {
     private config;
     private requestTimeout;
-    constructor(config: DiscordConfig);
+    constructor(config: DiscordConfig, masker?: (value: unknown) => unknown);
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private sendEmbedBatch;
     private sendMarkdownBatch;
@@ -410,7 +204,7 @@ declare class TelegramTransport extends BaseHttpTransport {
     private config;
     private apiUrl;
     private requestTimeout;
-    constructor(config: TelegramConfig);
+    constructor(config: TelegramConfig, masker?: (value: unknown) => unknown);
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private formatBatchMessage;
     private formatMarkdown;
@@ -428,7 +222,8 @@ declare class CloudWatchTransport extends BaseHttpTransport {
     private initialized;
     private initPromise;
     private resolvedLogStreamName;
-    constructor(config: CloudWatchConfig, configHostname?: string);
+    private maskReplacer;
+    constructor(config: CloudWatchConfig, configHostname?: string, maskReplacerFn?: MaskReplacer);
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private ensureInitialized;
     private initialize;
@@ -443,7 +238,7 @@ declare class ZohoCliqTransport extends BaseHttpTransport {
     private config;
     private endpoint;
     private requestTimeout;
-    constructor(config: ZohoCliqConfig);
+    constructor(config: ZohoCliqConfig, masker?: (value: unknown) => unknown);
     private buildEndpoint;
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private formatMessage;
@@ -473,14 +268,6 @@ declare function generateRequestId(options?: RequestIdOptions): string;
 declare function extractRequestId(headers: Record<string, string | string[] | undefined>): string | undefined;
 declare function getOrGenerateRequestId(headers: Record<string, string | string[] | undefined>, options?: RequestIdOptions): string;
 
-interface MaskSecretsOptions {
-    patterns?: string[];
-    mask?: string;
-    deep?: boolean;
-}
-declare function maskSecrets(obj: unknown, options?: MaskSecretsOptions): unknown;
-declare function createMasker(options?: MaskSecretsOptions): (obj: unknown) => unknown;
-
 declare function getCallerInfo(config: CallerConfig, additionalOffset?: number): CallerInfo | undefined;
 declare function formatCallerInfo(info: CallerInfo): string;
 
@@ -580,6 +367,7 @@ declare const CloudWatchConfigSchema: z.ZodType<CloudWatchConfig>;
 declare const ZohoCliqConfigSchema: z.ZodObject<{
     level: z.ZodOptional<z.ZodType<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown, z.core.$ZodTypeInternals<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown>>>;
     rules: z.ZodOptional<z.ZodArray<z.ZodType<LevelRule, unknown, z.core.$ZodTypeInternals<LevelRule, unknown>>>>;
+    respectRuntimeOverrides: z.ZodOptional<z.ZodBoolean>;
     batchSize: z.ZodOptional<z.ZodNumber>;
     flushInterval: z.ZodOptional<z.ZodNumber>;
     maxRetries: z.ZodOptional<z.ZodNumber>;
@@ -620,6 +408,7 @@ declare const LoggerConfigSchema: z.ZodObject<{
     zohoCliq: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         level: z.ZodOptional<z.ZodType<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown, z.core.$ZodTypeInternals<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown>>>;
         rules: z.ZodOptional<z.ZodArray<z.ZodType<LevelRule, unknown, z.core.$ZodTypeInternals<LevelRule, unknown>>>>;
+        respectRuntimeOverrides: z.ZodOptional<z.ZodBoolean>;
         batchSize: z.ZodOptional<z.ZodNumber>;
         flushInterval: z.ZodOptional<z.ZodNumber>;
         maxRetries: z.ZodOptional<z.ZodNumber>;
@@ -647,6 +436,7 @@ declare const LoggerConfigSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodArray<z.ZodObject<{
         level: z.ZodOptional<z.ZodType<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown, z.core.$ZodTypeInternals<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown>>>;
         rules: z.ZodOptional<z.ZodArray<z.ZodType<LevelRule, unknown, z.core.$ZodTypeInternals<LevelRule, unknown>>>>;
+        respectRuntimeOverrides: z.ZodOptional<z.ZodBoolean>;
         batchSize: z.ZodOptional<z.ZodNumber>;
         flushInterval: z.ZodOptional<z.ZodNumber>;
         maxRetries: z.ZodOptional<z.ZodNumber>;
@@ -676,6 +466,11 @@ declare const LoggerConfigSchema: z.ZodObject<{
     caller: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<CallerConfig, unknown, z.core.$ZodTypeInternals<CallerConfig, unknown>>]>>;
     hostname: z.ZodOptional<z.ZodString>;
     autoShutdown: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<AutoShutdownConfig, unknown, z.core.$ZodTypeInternals<AutoShutdownConfig, unknown>>]>>;
+    maskSecrets: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        patterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mask: z.ZodOptional<z.ZodString>;
+        deep: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>]>>;
 }, z.core.$strip>;
 declare function validateConfig(config: unknown): z.infer<typeof LoggerConfigSchema>;
 declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
@@ -691,6 +486,7 @@ declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
         apiKey: string;
         level?: "off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly" | undefined;
         rules?: LevelRule[] | undefined;
+        respectRuntimeOverrides?: boolean | undefined;
         batchSize?: number | undefined;
         flushInterval?: number | undefined;
         maxRetries?: number | undefined;
@@ -715,6 +511,7 @@ declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
         apiKey: string;
         level?: "off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly" | undefined;
         rules?: LevelRule[] | undefined;
+        respectRuntimeOverrides?: boolean | undefined;
         batchSize?: number | undefined;
         flushInterval?: number | undefined;
         maxRetries?: number | undefined;
@@ -738,6 +535,11 @@ declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
     caller?: boolean | CallerConfig | undefined;
     hostname?: string | undefined;
     autoShutdown?: boolean | AutoShutdownConfig | undefined;
+    maskSecrets?: boolean | {
+        patterns?: string[] | undefined;
+        mask?: string | undefined;
+        deep?: boolean | undefined;
+    } | undefined;
 }>;
 
-export { type AutoShutdownConfig, AutoShutdownConfigSchema, BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CallerConfig, CallerConfigSchema, type CallerInfo, type CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, type ConsoleConfig, ConsoleConfigSchema, type DiscordConfig, DiscordConfigSchema, DiscordTransport, type FileConfig, FileConfigSchema, type GracefulShutdownOptions, type HttpErrorData, type HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LOG_LEVELS, type LevelConfig, type LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, type LevelOverride, type LevelOverrideMatch, type LevelRule, LevelRuleSchema, type LogFormat, LogFormatSchema, type LogLevel, LogLevelSchema, type LogStreamName, LogStreamNameSchema, type LogStreamPattern, type LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, type LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, type LoggerConfig, LoggerConfigSchema, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RelayConfig, RelayConfigSchema, type RequestIdOptions, type SerializedError, type SingletonLogger, type TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, type ZohoCliqBotConfig, type ZohoCliqConfig, ZohoCliqConfigSchema, ZohoCliqTransport, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync, registerShutdown, safeValidateConfig, serializeError, validateConfig };
+export { AutoShutdownConfig, AutoShutdownConfigSchema, BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, CallerConfig, CallerConfigSchema, CallerInfo, CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, ConsoleConfig, ConsoleConfigSchema, DiscordConfig, DiscordConfigSchema, DiscordTransport, FileConfig, FileConfigSchema, type GracefulShutdownOptions, type HttpErrorData, HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LevelConfig, LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, LevelOverride, LevelOverrideMatch, LevelRule, LevelRuleSchema, LogFormat, LogFormatSchema, LogLevel, LogLevelSchema, LogStreamName, LogStreamNameSchema, LogStreamPattern, LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, LoggerConfig, LoggerConfigSchema, LoggerContext, LoggerStore, MaskReplacer, MessageBuffer, Meta, RelayConfig, RelayConfigSchema, type RequestIdOptions, type SerializedError, type SingletonLogger, TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, ZohoCliqConfig, ZohoCliqConfigSchema, ZohoCliqTransport, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, matchesContext, measureAsync, measureSync, registerShutdown, safeValidateConfig, serializeError, validateConfig };