@rawnodes/logger 1.7.0 → 1.8.0

package/README.md

@@ -105,6 +105,198 @@ const logger = Logger.create({
 });
 ```
 
+### Per-Transport Level
+
+Each transport can have its own log level:
+
+```typescript
+const logger = Logger.create({
+  level: 'silly',                        // accept all at logger level
+  console: {
+    format: 'plain',
+    level: 'debug',                      // console: debug and above
+  },
+  file: {
+    format: 'json',
+    level: 'warn',                       // file: only warn and error
+    dirname: 'logs',
+    filename: 'app-%DATE%.log',
+  },
+});
+```
+
+| Scenario | Console | File |
+|----------|---------|------|
+| Development | `debug` | — |
+| Production | `info` | `warn` |
+| Troubleshooting | `debug` | `info` |
+| Critical alerts | `info` | `error` |
+
+This is useful for sending only critical errors to alerting systems while keeping verbose logs in console.
+
+### Per-Transport Rules
+
+Each transport can have its own filtering rules. Use `level: 'off'` with rules to create a whitelist pattern:
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  file: {
+    format: 'json',
+    level: 'off',                              // off by default
+    rules: [
+      { match: { context: 'payments' }, level: 'error' },  // only errors from payments
+      { match: { context: 'auth' }, level: 'warn' },       // warn+ from auth
+    ],
+    dirname: 'logs',
+    filename: 'critical-%DATE%.log',
+  },
+});
+
+// Only error logs from 'payments' context go to file
+logger.for('payments').error('Payment failed');  // → file
+logger.for('payments').info('Processing');       // ✗ not logged to file
+logger.for('other').error('Generic error');      // ✗ not logged to file (no matching rule)
+```
+
+Rules can also match store context (AsyncLocalStorage):
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  file: {
+    format: 'json',
+    level: 'off',
+    rules: [
+      { match: { userId: 123 }, level: 'debug' },           // debug for specific user
+      { match: { context: 'api', premium: true }, level: 'debug' }, // debug for premium API users
+    ],
+    dirname: 'logs',
+    filename: 'debug-%DATE%.log',
+  },
+});
+
+// Logs for user 123 go to file
+store.run({ userId: 123 }, () => {
+  logger.debug('User action');  // → file
+});
+```
+
+Use `level: 'off'` in rules to suppress specific contexts:
+
+```typescript
+const logger = Logger.create({
+  level: 'debug',
+  console: {
+    format: 'plain',
+    level: 'debug',
+    rules: [
+      { match: { context: 'noisy-module' }, level: 'off' },  // suppress noisy logs
+    ],
+  },
+});
+
+logger.for('noisy-module').debug('Spam');  // ✗ not logged
+logger.for('other').debug('Useful info');  // → logged
+```
+
+## External Transports
+
+### Discord
+
+Send logs to Discord via webhooks with rich embeds:
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  discord: {
+    webhookUrl: 'https://discord.com/api/webhooks/xxx/yyy',
+    level: 'error',                    // only errors to Discord
+    username: 'My App Logger',         // optional bot name
+    avatarUrl: 'https://...',          // optional avatar
+    embedColors: {                     // optional custom colors
+      error: 0xFF0000,
+      warn: 0xFFAA00,
+    },
+    batchSize: 10,                     // messages per batch (default: 10)
+    flushInterval: 2000,               // flush interval ms (default: 2000)
+  },
+});
+```
+
+### Telegram
+
+Send logs to Telegram chats/channels:
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  telegram: {
+    botToken: process.env.TG_BOT_TOKEN!,
+    chatId: process.env.TG_CHAT_ID!,
+    level: 'warn',                     // warn and above
+    parseMode: 'Markdown',             // 'Markdown' | 'MarkdownV2' | 'HTML'
+    disableNotification: false,        // mute non-error by default
+    threadId: 123,                     // optional forum topic ID
+    replyToMessageId: 456,             // optional reply to message
+    batchSize: 20,                     // default: 20
+    flushInterval: 1000,               // default: 1000
+  },
+});
+```
+
+Use `level: 'off'` with rules for selective logging:
+
+```typescript
+telegram: {
+  botToken: '...',
+  chatId: '...',
+  level: 'off',                        // off by default
+  rules: [
+    { match: { context: 'payments' }, level: 'error' },  // only payment errors
+  ],
+}
+```
+
+### CloudWatch
+
+Send logs to AWS CloudWatch Logs:
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  cloudwatch: {
+    logGroupName: '/app/my-service',
+    logStreamName: `${hostname}-${Date.now()}`,
+    region: 'us-east-1',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    createLogGroup: true,              // auto-create group (default: false)
+    createLogStream: true,             // auto-create stream (default: true)
+    batchSize: 100,                    // default: 100
+    flushInterval: 1000,               // default: 1000
+  },
+});
+```
+
+### Transport Options
+
+All external transports support:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `level` | — | Log level filter |
+| `rules` | — | Per-transport filtering rules |
+| `batchSize` | varies | Max messages per batch |
+| `flushInterval` | varies | Flush interval in ms |
+| `maxRetries` | 3 | Retry count on failure |
+| `retryDelay` | 1000 | Base retry delay in ms |
+
 ## Singleton Pattern
 
 For app-wide logging:
@@ -312,7 +504,7 @@ class Logger<TContext> {
 ### Types
 
 ```typescript
-type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly';
+type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly' | 'off';
 type LogFormat = 'json' | 'plain' | 'logfmt' | 'simple';
 type Meta = object | (() => object);
 
@@ -321,9 +513,15 @@ interface LoggerConfig {
     default: LogLevel;
     rules?: LevelRule[];
   };
-  console: { format: LogFormat };
+  console: {
+    format: LogFormat;
+    level?: LogLevel;      // optional, overrides global level
+    rules?: LevelRule[];   // optional, per-transport filtering
+  };
   file?: {
     format: LogFormat;
+    level?: LogLevel;      // optional, overrides global level
+    rules?: LevelRule[];   // optional, per-transport filtering
     dirname: string;
     filename: string;
     datePattern?: string;

package/dist/index.d.mts

@@ -1,4 +1,7 @@
+import TransportStream from 'winston-transport';
+
 declare const LOG_LEVELS: {
+    readonly off: -1;
     readonly error: 0;
     readonly warn: 1;
     readonly info: 2;
@@ -11,11 +14,21 @@ 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;
@@ -23,11 +36,39 @@ interface FileConfig {
     maxSize?: string;
     maxFiles?: string;
 }
-interface LevelRule {
-    match: Record<string, unknown> & {
-        context?: string;
-    };
-    level: LogLevel;
+interface HttpTransportBaseConfig {
+    level?: LogLevel;
+    rules?: LevelRule[];
+    batchSize?: number;
+    flushInterval?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+interface DiscordConfig extends HttpTransportBaseConfig {
+    webhookUrl: string;
+    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 CloudWatchConfig extends HttpTransportBaseConfig {
+    logGroupName: string;
+    logStreamName: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    createLogGroup?: boolean;
+    createLogStream?: boolean;
 }
 interface LevelConfigObject {
     default: LogLevel;
@@ -38,6 +79,9 @@ interface LoggerConfig {
     level: LevelConfig;
     console: ConsoleConfig;
     file?: FileConfig;
+    discord?: DiscordConfig;
+    telegram?: TelegramConfig;
+    cloudwatch?: CloudWatchConfig;
 }
 type LoggerContext = Record<string, unknown>;
 type LevelOverrideMatch<TContext extends LoggerContext> = Partial<TContext> & {
@@ -90,6 +134,98 @@ interface SingletonLogger<TContext extends LoggerContext> {
 }
 declare function createSingletonLogger<TContext extends LoggerContext = LoggerContext>(): SingletonLogger<TContext>;
 
+declare function matchesContext(storeContext: LoggerContext | undefined, loggerContext: string | undefined, match: Record<string, unknown> & {
+    context?: string;
+}): boolean;
+
+interface BufferedMessage {
+    level: LogLevel;
+    message: string;
+    timestamp: Date;
+    context?: string;
+    meta?: Record<string, unknown>;
+}
+interface BufferOptions {
+    batchSize: number;
+    flushInterval: number;
+    maxRetries: number;
+    retryDelay: number;
+    onFlush: (messages: BufferedMessage[]) => Promise<void>;
+    onError?: (error: Error, messages: BufferedMessage[]) => void;
+}
+declare class MessageBuffer {
+    private options;
+    private queue;
+    private timer;
+    private flushing;
+    private closed;
+    constructor(options: BufferOptions);
+    add(message: BufferedMessage): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private scheduleFlush;
+    private clearTimer;
+    private sendWithRetry;
+    private delay;
+}
+
+interface BaseHttpTransportOptions {
+    batchSize?: number;
+    flushInterval?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+declare abstract class BaseHttpTransport extends TransportStream {
+    protected buffer: MessageBuffer;
+    constructor(opts?: BaseHttpTransportOptions);
+    log(info: Record<string, unknown>, callback: () => void): void;
+    close(): Promise<void>;
+    protected transformMessage(info: Record<string, unknown>): BufferedMessage;
+    protected handleError(error: Error, messages: BufferedMessage[]): void;
+    protected abstract sendBatch(messages: BufferedMessage[]): Promise<void>;
+}
+
+declare class DiscordTransport extends BaseHttpTransport {
+    private config;
+    constructor(config: DiscordConfig);
+    protected sendBatch(messages: BufferedMessage[]): Promise<void>;
+    private createEmbed;
+    private metaToFields;
+    private sendWebhook;
+    private chunkArray;
+}
+
+declare class TelegramTransport extends BaseHttpTransport {
+    private config;
+    private apiUrl;
+    constructor(config: TelegramConfig);
+    protected sendBatch(messages: BufferedMessage[]): Promise<void>;
+    private formatBatchMessage;
+    private formatMarkdown;
+    private formatHtml;
+    private shouldMute;
+    private sendMessage;
+    private escapeMarkdownV2;
+    private escapeHtml;
+}
+
+declare class CloudWatchTransport extends BaseHttpTransport {
+    private config;
+    private client;
+    private sequenceToken;
+    private initialized;
+    private initPromise;
+    constructor(config: CloudWatchConfig);
+    protected sendBatch(messages: BufferedMessage[]): Promise<void>;
+    private ensureInitialized;
+    private initialize;
+    private createLogGroupIfNotExists;
+    private createLogStreamIfNotExists;
+    private fetchSequenceToken;
+    private isResourceAlreadyExistsError;
+    private isInvalidSequenceTokenError;
+}
+
 interface TimingResult {
     label: string;
     durationMs: number;
@@ -124,4 +260,4 @@ declare function flattenObject(obj: Record<string, unknown>, prefix?: string): R
 declare function formatLogfmtValue(value: unknown): string;
 declare function formatLogfmt(data: Record<string, unknown>): string;
 
-export { type ConsoleConfig, type FileConfig, LOG_LEVELS, type LevelConfig, type LevelConfigObject, type LevelOverride, type LevelOverrideMatch, type LevelRule, type LogFormat, type LogLevel, Logger, type LoggerConfig, type LoggerContext, LoggerStore, type MaskSecretsOptions, type Meta, type RequestIdOptions, type SingletonLogger, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatLogfmt, formatLogfmtValue, generateRequestId, getOrGenerateRequestId, isValidLogLevel, maskSecrets, measureAsync, measureSync };
+export { BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CloudWatchConfig, CloudWatchTransport, type ConsoleConfig, type DiscordConfig, DiscordTransport, type FileConfig, type HttpTransportBaseConfig, LOG_LEVELS, type LevelConfig, type LevelConfigObject, type LevelOverride, type LevelOverrideMatch, type LevelRule, type LogFormat, type LogLevel, Logger, type LoggerConfig, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RequestIdOptions, type SingletonLogger, type TelegramConfig, TelegramTransport, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatLogfmt, formatLogfmtValue, generateRequestId, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync };

package/dist/index.d.ts

@@ -1,4 +1,7 @@
+import TransportStream from 'winston-transport';
+
 declare const LOG_LEVELS: {
+    readonly off: -1;
     readonly error: 0;
     readonly warn: 1;
     readonly info: 2;
@@ -11,11 +14,21 @@ 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;
@@ -23,11 +36,39 @@ interface FileConfig {
     maxSize?: string;
     maxFiles?: string;
 }
-interface LevelRule {
-    match: Record<string, unknown> & {
-        context?: string;
-    };
-    level: LogLevel;
+interface HttpTransportBaseConfig {
+    level?: LogLevel;
+    rules?: LevelRule[];
+    batchSize?: number;
+    flushInterval?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+interface DiscordConfig extends HttpTransportBaseConfig {
+    webhookUrl: string;
+    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 CloudWatchConfig extends HttpTransportBaseConfig {
+    logGroupName: string;
+    logStreamName: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    createLogGroup?: boolean;
+    createLogStream?: boolean;
 }
 interface LevelConfigObject {
     default: LogLevel;
@@ -38,6 +79,9 @@ interface LoggerConfig {
     level: LevelConfig;
     console: ConsoleConfig;
     file?: FileConfig;
+    discord?: DiscordConfig;
+    telegram?: TelegramConfig;
+    cloudwatch?: CloudWatchConfig;
 }
 type LoggerContext = Record<string, unknown>;
 type LevelOverrideMatch<TContext extends LoggerContext> = Partial<TContext> & {
@@ -90,6 +134,98 @@ interface SingletonLogger<TContext extends LoggerContext> {
 }
 declare function createSingletonLogger<TContext extends LoggerContext = LoggerContext>(): SingletonLogger<TContext>;
 
+declare function matchesContext(storeContext: LoggerContext | undefined, loggerContext: string | undefined, match: Record<string, unknown> & {
+    context?: string;
+}): boolean;
+
+interface BufferedMessage {
+    level: LogLevel;
+    message: string;
+    timestamp: Date;
+    context?: string;
+    meta?: Record<string, unknown>;
+}
+interface BufferOptions {
+    batchSize: number;
+    flushInterval: number;
+    maxRetries: number;
+    retryDelay: number;
+    onFlush: (messages: BufferedMessage[]) => Promise<void>;
+    onError?: (error: Error, messages: BufferedMessage[]) => void;
+}
+declare class MessageBuffer {
+    private options;
+    private queue;
+    private timer;
+    private flushing;
+    private closed;
+    constructor(options: BufferOptions);
+    add(message: BufferedMessage): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private scheduleFlush;
+    private clearTimer;
+    private sendWithRetry;
+    private delay;
+}
+
+interface BaseHttpTransportOptions {
+    batchSize?: number;
+    flushInterval?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+declare abstract class BaseHttpTransport extends TransportStream {
+    protected buffer: MessageBuffer;
+    constructor(opts?: BaseHttpTransportOptions);
+    log(info: Record<string, unknown>, callback: () => void): void;
+    close(): Promise<void>;
+    protected transformMessage(info: Record<string, unknown>): BufferedMessage;
+    protected handleError(error: Error, messages: BufferedMessage[]): void;
+    protected abstract sendBatch(messages: BufferedMessage[]): Promise<void>;
+}
+
+declare class DiscordTransport extends BaseHttpTransport {
+    private config;
+    constructor(config: DiscordConfig);
+    protected sendBatch(messages: BufferedMessage[]): Promise<void>;
+    private createEmbed;
+    private metaToFields;
+    private sendWebhook;
+    private chunkArray;
+}
+
+declare class TelegramTransport extends BaseHttpTransport {
+    private config;
+    private apiUrl;
+    constructor(config: TelegramConfig);
+    protected sendBatch(messages: BufferedMessage[]): Promise<void>;
+    private formatBatchMessage;
+    private formatMarkdown;
+    private formatHtml;
+    private shouldMute;
+    private sendMessage;
+    private escapeMarkdownV2;
+    private escapeHtml;
+}
+
+declare class CloudWatchTransport extends BaseHttpTransport {
+    private config;
+    private client;
+    private sequenceToken;
+    private initialized;
+    private initPromise;
+    constructor(config: CloudWatchConfig);
+    protected sendBatch(messages: BufferedMessage[]): Promise<void>;
+    private ensureInitialized;
+    private initialize;
+    private createLogGroupIfNotExists;
+    private createLogStreamIfNotExists;
+    private fetchSequenceToken;
+    private isResourceAlreadyExistsError;
+    private isInvalidSequenceTokenError;
+}
+
 interface TimingResult {
     label: string;
     durationMs: number;
@@ -124,4 +260,4 @@ declare function flattenObject(obj: Record<string, unknown>, prefix?: string): R
 declare function formatLogfmtValue(value: unknown): string;
 declare function formatLogfmt(data: Record<string, unknown>): string;
 
-export { type ConsoleConfig, type FileConfig, LOG_LEVELS, type LevelConfig, type LevelConfigObject, type LevelOverride, type LevelOverrideMatch, type LevelRule, type LogFormat, type LogLevel, Logger, type LoggerConfig, type LoggerContext, LoggerStore, type MaskSecretsOptions, type Meta, type RequestIdOptions, type SingletonLogger, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatLogfmt, formatLogfmtValue, generateRequestId, getOrGenerateRequestId, isValidLogLevel, maskSecrets, measureAsync, measureSync };
+export { BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CloudWatchConfig, CloudWatchTransport, type ConsoleConfig, type DiscordConfig, DiscordTransport, type FileConfig, type HttpTransportBaseConfig, LOG_LEVELS, type LevelConfig, type LevelConfigObject, type LevelOverride, type LevelOverrideMatch, type LevelRule, type LogFormat, type LogLevel, Logger, type LoggerConfig, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RequestIdOptions, type SingletonLogger, type TelegramConfig, TelegramTransport, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatLogfmt, formatLogfmtValue, generateRequestId, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync };