@rawnodes/logger 1.7.0 → 1.9.0

package/README.md

@@ -105,6 +105,231 @@ 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 |
+
+### Multiple Transports
+
+You can configure multiple instances of the same transport type using arrays:
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  discord: [
+    {
+      webhookUrl: 'https://discord.com/api/webhooks/payments/xxx',
+      level: 'off',
+      rules: [{ match: { context: 'payments' }, level: 'error' }],
+    },
+    {
+      webhookUrl: 'https://discord.com/api/webhooks/auth/yyy',
+      level: 'off',
+      rules: [{ match: { context: 'auth' }, level: 'error' }],
+    },
+  ],
+  telegram: [
+    { botToken: 'token1', chatId: 'errors-chat', level: 'error' },
+    { botToken: 'token2', chatId: 'alerts-chat', level: 'warn' },
+  ],
+});
+
+// Payment errors go to payments Discord channel
+logger.for('payments').error('Payment failed');
+
+// Auth errors go to auth Discord channel
+logger.for('auth').error('Login failed');
+```
+
 ## Singleton Pattern
 
 For app-wide logging:
@@ -312,7 +537,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 +546,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;