@rawnodes/logger 2.8.0 → 2.9.0

package/README.md

@@ -136,16 +136,57 @@ This is useful for sending only critical errors to alerting systems while keepin
 
 #### Level precedence
 
-When deciding whether to emit a log entry, the following order applies — **most specific wins**:
+Each transport decides on its own whether to emit a given log entry. The precedence depends on whether the transport **respects runtime overrides** (see the next section):
 
-1. **Global override** from `setLevelOverride(...)` or the top-level `level.rules` array
+**When respecting overrides** (observability transports — console/file/cloudwatch/relay by default):
+
+1. **Runtime override** from `setLevelOverride(...)` or the top-level `level.rules` array
 2. **Per-transport rule** (a matching entry in `console.rules` / `file.rules` / etc.)
 3. **Per-transport level** (`console.level`, `file.level`, …)
 4. **Global default level** (`level` or `level.default`)
 
-Practically: a matching `setLevelOverride({ userId: 123 }, 'debug')` will surface debug logs to **every** transport, even one whose own `level` is set to `info`. This is intentional — dynamic overrides are for targeted troubleshooting, and they wouldn't be useful if a downstream transport could silently swallow the messages they just enabled.
+**When ignoring overrides** (alert transports — discord/telegram/zohoCliq by default):
+
+1. **Per-transport rule**
+2. **Per-transport level**
+3. **Global default level**
+
+Practically: a matching `setLevelOverride({ userId: 123 }, 'debug')` will surface debug logs to **viewing** transports (console/cloudwatch/file), even if their own `level` is set to `info`. But the same override will **not** leak through notification channels (discord/telegram/zohoCliq) unless you explicitly opt them in via `respectRuntimeOverrides: true`.
+
+#### Transport roles (`respectRuntimeOverrides`)
+
+Every transport config accepts an optional `respectRuntimeOverrides?: boolean` flag. Defaults:
 
-If you need a transport to stay narrow while overrides are active, use `rules` on that transport (level 2), not the plain `level` field.
+| Transport    | Default | Role          |
+|--------------|---------|---------------|
+| `console`    | `true`  | observability |
+| `file`       | `true`  | observability |
+| `cloudwatch` | `true`  | observability |
+| `relay`      | `true`  | observability |
+| `discord`    | `false` | alert         |
+| `telegram`   | `false` | alert         |
+| `zohoCliq`   | `false` | alert         |
+
+The defaults reflect typical usage — console/file/cloudwatch are where operators look for logs during troubleshooting, while discord/telegram/zohoCliq are user-facing notification channels that should not get flooded by ad-hoc debug overrides. Override the default per-transport when needed:
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  telegram: {
+    botToken: '...',
+    chatId: '...',
+    level: 'warn',
+    respectRuntimeOverrides: true,   // let overrides through (rare)
+  },
+  cloudwatch: {
+    logGroupName: '...',
+    level: 'info',
+    respectRuntimeOverrides: false,  // strict gate even under troubleshooting (also rare)
+    region: '...', accessKeyId: '...', secretAccessKey: '...',
+  },
+});
+```
 
 ### Per-Transport Rules
 

package/dist/index.d.mts

@@ -20,15 +20,34 @@ interface LevelRule {
     };
     level: LogLevel;
 }
+/**
+ * Controls whether a transport respects runtime level overrides registered via
+ * `setLevelOverride(...)` (or the top-level `level.rules` in the logger config).
+ *
+ * When `true` (the default for observability transports — console/file/cloudwatch/relay):
+ * a matching override bypasses the transport's own `level`/`rules` so that
+ * targeted troubleshooting actually surfaces logs in the viewing channels.
+ *
+ * When `false` (the default for alert-style transports — discord/telegram/zohoCliq):
+ * the transport filters strictly by its own `level`/`rules` and ignores runtime
+ * overrides, which prevents ad-hoc debug overrides from flooding user-facing
+ * notification channels.
+ *
+ * Every transport config accepts this flag; the only time it needs to be set
+ * explicitly is when overriding the default for the transport kind.
+ */
+type RespectRuntimeOverrides = boolean;
 interface ConsoleConfig {
     format: LogFormat;
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
 }
 interface FileConfig {
     format: LogFormat;
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
     dirname: string;
     filename: string;
     datePattern?: string;
@@ -40,6 +59,7 @@ interface FileConfig {
 interface HttpTransportBaseConfig {
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
     batchSize?: number;
     flushInterval?: number;
     maxRetries?: number;
@@ -155,6 +175,8 @@ interface RelayConfig {
     reconnectDelay?: number;
     /** Max reconnect delay in ms (default: 30000) */
     maxReconnectDelay?: number;
+    /** See RespectRuntimeOverrides. Default: true (relay is an observability transport). */
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
 }
 interface CloudWatchConfig extends HttpTransportBaseConfig {
     logGroupName: string;
@@ -580,6 +602,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 +643,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 +671,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>;
@@ -691,6 +716,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 +741,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;

package/dist/index.d.ts

@@ -20,15 +20,34 @@ interface LevelRule {
     };
     level: LogLevel;
 }
+/**
+ * Controls whether a transport respects runtime level overrides registered via
+ * `setLevelOverride(...)` (or the top-level `level.rules` in the logger config).
+ *
+ * When `true` (the default for observability transports — console/file/cloudwatch/relay):
+ * a matching override bypasses the transport's own `level`/`rules` so that
+ * targeted troubleshooting actually surfaces logs in the viewing channels.
+ *
+ * When `false` (the default for alert-style transports — discord/telegram/zohoCliq):
+ * the transport filters strictly by its own `level`/`rules` and ignores runtime
+ * overrides, which prevents ad-hoc debug overrides from flooding user-facing
+ * notification channels.
+ *
+ * Every transport config accepts this flag; the only time it needs to be set
+ * explicitly is when overriding the default for the transport kind.
+ */
+type RespectRuntimeOverrides = boolean;
 interface ConsoleConfig {
     format: LogFormat;
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
 }
 interface FileConfig {
     format: LogFormat;
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
     dirname: string;
     filename: string;
     datePattern?: string;
@@ -40,6 +59,7 @@ interface FileConfig {
 interface HttpTransportBaseConfig {
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
     batchSize?: number;
     flushInterval?: number;
     maxRetries?: number;
@@ -155,6 +175,8 @@ interface RelayConfig {
     reconnectDelay?: number;
     /** Max reconnect delay in ms (default: 30000) */
     maxReconnectDelay?: number;
+    /** See RespectRuntimeOverrides. Default: true (relay is an observability transport). */
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
 }
 interface CloudWatchConfig extends HttpTransportBaseConfig {
     logGroupName: string;
@@ -580,6 +602,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 +643,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 +671,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>;
@@ -691,6 +716,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 +741,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;

package/dist/index.js

@@ -789,13 +789,27 @@ function getLevelName(levelNum) {
   if (levelNum >= 20) return "debug";
   return "silly";
 }
-function shouldPassTransport(log, level, rules, state) {
+var DEFAULT_RESPECTS_OVERRIDES = {
+  console: true,
+  file: true,
+  cloudwatch: true,
+  relay: true,
+  discord: false,
+  telegram: false,
+  zohoCliq: false
+};
+function resolveRespectsOverrides(kind, configFlag) {
+  return configFlag ?? DEFAULT_RESPECTS_OVERRIDES[kind];
+}
+function shouldPassTransport(log, level, rules, state, respectOverrides) {
   const logLevel = getLevelName(log.level);
-  const embeddedOverride = log.__or;
-  if (typeof embeddedOverride === "string") {
-    if (embeddedOverride === "off") return false;
-    const overrideLevel = embeddedOverride;
-    return LOG_LEVELS[logLevel] <= LOG_LEVELS[overrideLevel];
+  if (respectOverrides) {
+    const embeddedOverride = log.__or;
+    if (typeof embeddedOverride === "string") {
+      if (embeddedOverride === "off") return false;
+      const overrideLevel = embeddedOverride;
+      return LOG_LEVELS[logLevel] <= LOG_LEVELS[overrideLevel];
+    }
   }
   const context = log.context;
   if (rules && rules.length > 0) {
@@ -874,7 +888,7 @@ function formatLog(log, format, store) {
   return `[${timestamp}] ${levelName}: ${message}
 `;
 }
-function createFormattedFilterStream(format, level, rules, state, destination) {
+function createFormattedFilterStream(format, level, rules, state, destination, respectOverrides) {
   return new stream.Transform({
     transform(chunk, _encoding, callback) {
       const line = chunk.toString().trim();
@@ -887,7 +901,7 @@ function createFormattedFilterStream(format, level, rules, state, destination) {
         callback();
         return;
       }
-      if (!shouldPassTransport(log, level, rules, state)) {
+      if (!shouldPassTransport(log, level, rules, state, respectOverrides)) {
         callback();
         return;
       }
@@ -905,7 +919,8 @@ function createStreams(config, state) {
     config.console.level,
     config.console.rules,
     state,
-    process.stdout
+    process.stdout,
+    resolveRespectsOverrides("console", config.console.respectRuntimeOverrides)
   );
   streams.push({
     level: "trace",
@@ -938,7 +953,8 @@ function createStreams(config, state) {
       fileConfig.level,
       fileConfig.rules,
       state,
-      rotatingStream
+      rotatingStream,
+      resolveRespectsOverrides("file", fileConfig.respectRuntimeOverrides)
     );
     streams.push({
       level: "trace",
@@ -948,7 +964,13 @@ function createStreams(config, state) {
   for (const discordConfig of toArray(config.discord)) {
     const transport = new DiscordTransport(discordConfig);
     transports.push(transport);
-    const discordStream = createHttpTransportStream(transport, discordConfig.level, discordConfig.rules, state);
+    const discordStream = createHttpTransportStream(
+      transport,
+      discordConfig.level,
+      discordConfig.rules,
+      state,
+      resolveRespectsOverrides("discord", discordConfig.respectRuntimeOverrides)
+    );
     streams.push({
       level: "trace",
       stream: discordStream
@@ -957,7 +979,13 @@ function createStreams(config, state) {
   for (const telegramConfig of toArray(config.telegram)) {
     const transport = new TelegramTransport(telegramConfig);
     transports.push(transport);
-    const telegramStream = createHttpTransportStream(transport, telegramConfig.level, telegramConfig.rules, state);
+    const telegramStream = createHttpTransportStream(
+      transport,
+      telegramConfig.level,
+      telegramConfig.rules,
+      state,
+      resolveRespectsOverrides("telegram", telegramConfig.respectRuntimeOverrides)
+    );
     streams.push({
       level: "trace",
       stream: telegramStream
@@ -966,7 +994,13 @@ function createStreams(config, state) {
   for (const zohoCliqConfig of toArray(config.zohoCliq)) {
     const transport = new ZohoCliqTransport(zohoCliqConfig);
     transports.push(transport);
-    const zohoStream = createHttpTransportStream(transport, zohoCliqConfig.level, zohoCliqConfig.rules, state);
+    const zohoStream = createHttpTransportStream(
+      transport,
+      zohoCliqConfig.level,
+      zohoCliqConfig.rules,
+      state,
+      resolveRespectsOverrides("zohoCliq", zohoCliqConfig.respectRuntimeOverrides)
+    );
     streams.push({
       level: "trace",
       stream: zohoStream
@@ -975,7 +1009,13 @@ function createStreams(config, state) {
   for (const cloudwatchConfig of toArray(config.cloudwatch)) {
     const transport = new CloudWatchTransport(cloudwatchConfig, config.hostname);
     transports.push(transport);
-    const cwStream = createHttpTransportStream(transport, cloudwatchConfig.level, cloudwatchConfig.rules, state);
+    const cwStream = createHttpTransportStream(
+      transport,
+      cloudwatchConfig.level,
+      cloudwatchConfig.rules,
+      state,
+      resolveRespectsOverrides("cloudwatch", cloudwatchConfig.respectRuntimeOverrides)
+    );
     streams.push({
       level: "trace",
       stream: cwStream
@@ -1000,7 +1040,7 @@ function toArray(value) {
   if (!value) return [];
   return Array.isArray(value) ? value : [value];
 }
-function createHttpTransportStream(transport, level, rules, state) {
+function createHttpTransportStream(transport, level, rules, state, respectOverrides) {
   return new stream.Writable({
     write(chunk, _encoding, callback) {
       const line = chunk.toString().trim();
@@ -1013,7 +1053,7 @@ function createHttpTransportStream(transport, level, rules, state) {
         callback();
         return;
       }
-      if (!shouldPassTransport(log, level, rules, state)) {
+      if (!shouldPassTransport(log, level, rules, state, respectOverrides)) {
         callback();
         return;
       }
@@ -1172,12 +1212,14 @@ var LevelRuleSchema = zod.z.object({
 var ConsoleConfigSchema = zod.z.object({
   format: LogFormatSchema,
   level: LogLevelSchema.optional(),
-  rules: zod.z.array(LevelRuleSchema).optional()
+  rules: zod.z.array(LevelRuleSchema).optional(),
+  respectRuntimeOverrides: zod.z.boolean().optional()
 });
 var FileConfigSchema = zod.z.object({
   format: LogFormatSchema,
   level: LogLevelSchema.optional(),
   rules: zod.z.array(LevelRuleSchema).optional(),
+  respectRuntimeOverrides: zod.z.boolean().optional(),
   dirname: zod.z.string().min(1, "dirname is required"),
   filename: zod.z.string().min(1, "filename is required"),
   datePattern: zod.z.string().optional(),
@@ -1189,6 +1231,7 @@ var FileConfigSchema = zod.z.object({
 var HttpTransportBaseConfigSchema = zod.z.object({
   level: LogLevelSchema.optional(),
   rules: zod.z.array(LevelRuleSchema).optional(),
+  respectRuntimeOverrides: zod.z.boolean().optional(),
   batchSize: zod.z.number().int().positive().optional(),
   flushInterval: zod.z.number().int().positive().optional(),
   maxRetries: zod.z.number().int().nonnegative().optional(),
@@ -1202,6 +1245,7 @@ var HttpTransportBaseConfigSchema = zod.z.object({
 var DiscordConfigSchema = zod.z.object({
   level: LogLevelSchema.optional(),
   rules: zod.z.array(LevelRuleSchema).optional(),
+  respectRuntimeOverrides: zod.z.boolean().optional(),
   batchSize: zod.z.number().int().positive().optional(),
   flushInterval: zod.z.number().int().positive().optional(),
   maxRetries: zod.z.number().int().nonnegative().optional(),
@@ -1223,6 +1267,7 @@ var DiscordConfigSchema = zod.z.object({
 var TelegramConfigSchema = zod.z.object({
   level: LogLevelSchema.optional(),
   rules: zod.z.array(LevelRuleSchema).optional(),
+  respectRuntimeOverrides: zod.z.boolean().optional(),
   batchSize: zod.z.number().int().positive().optional(),
   flushInterval: zod.z.number().int().positive().optional(),
   maxRetries: zod.z.number().int().nonnegative().optional(),
@@ -1260,6 +1305,7 @@ var LogStreamNameSchema = zod.z.union([
 var CloudWatchConfigSchema = zod.z.object({
   level: LogLevelSchema.optional(),
   rules: zod.z.array(LevelRuleSchema).optional(),
+  respectRuntimeOverrides: zod.z.boolean().optional(),
   batchSize: zod.z.number().int().positive().optional(),
   flushInterval: zod.z.number().int().positive().optional(),
   maxRetries: zod.z.number().int().nonnegative().optional(),
@@ -1280,6 +1326,7 @@ var CloudWatchConfigSchema = zod.z.object({
 var ZohoCliqConfigBaseSchema = zod.z.object({
   level: LogLevelSchema.optional(),
   rules: zod.z.array(LevelRuleSchema).optional(),
+  respectRuntimeOverrides: zod.z.boolean().optional(),
   batchSize: zod.z.number().int().positive().optional(),
   flushInterval: zod.z.number().int().positive().optional(),
   maxRetries: zod.z.number().int().nonnegative().optional(),
@@ -1312,7 +1359,8 @@ var RelayConfigSchema = zod.z.object({
   pollInterval: zod.z.number().int().positive().optional(),
   bufferSize: zod.z.number().int().positive().optional(),
   reconnectDelay: zod.z.number().int().positive().optional(),
-  maxReconnectDelay: zod.z.number().int().positive().optional()
+  maxReconnectDelay: zod.z.number().int().positive().optional(),
+  respectRuntimeOverrides: zod.z.boolean().optional()
 });
 var LevelConfigObjectSchema = zod.z.object({
   default: LogLevelSchema,