@warlock.js/logger 4.1.15 → 4.2.0

package/esm/channels/file-log.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"file-log.mjs","names":[],"sources":["../../../../../../@warlock.js/logger/src/channels/file-log.ts"],"sourcesContent":["import { ensureDirectoryAsync } from \"@warlock.js/fs\";\r\nimport dayjs from \"dayjs\";\r\nimport fs from \"fs\";\r\nimport { EOL } from \"os\";\r\nimport path from \"path\";\r\nimport { LogChannel } from \"../log-channel\";\r\nimport type {\r\n  BasicLogConfigurations,\r\n  LogContract,\r\n  LoggingData,\r\n  LogLevel,\r\n  LogMessage,\r\n} from \"../types\";\r\n\r\n// TODO: Add max messages per file before rotation\r\n\r\nexport type FileLogConfig = BasicLogConfigurations & {\r\n  storagePath?: string;\r\n  /**\r\n   * File name, without extension\r\n   */\r\n  name?: string;\r\n  /**\r\n   * chunk mode\r\n   * If set to `single`, the logs will be created in a single file, unless the rotate is set to true\r\n   * If set to `daily`, the logs will be created in a daily file, unless the rotate is set to true\r\n   * If set to `hourly`, the logs will be created in an hourly file, unless the rotate is set to true\r\n   * @default single\r\n   */\r\n  chunk?: \"single\" | \"daily\" | \"hourly\";\r\n  /**\r\n   * Whether to rotate the file\r\n   *\r\n   * @default true\r\n   */\r\n  rotate?: boolean;\r\n  /**\r\n   * File Extension\r\n   *\r\n   * @default log\r\n   */\r\n  extension?: string;\r\n  /**\r\n   * If rotate is set, the rotate name will be added to the file name suffixed with `-`\r\n   *\r\n   * @default DD-MM-YYYY\r\n   */\r\n  rotateFileName?: string;\r\n  /**\r\n   * Max file size before rotating the file\r\n   *\r\n   * @default 10MB\r\n   */\r\n  maxFileSize?: number;\r\n  /**\r\n   * Set the max messages that needs to be added before writing to the file\r\n   *\r\n   * @default 100\r\n   */\r\n  maxMessagesToWrite?: number;\r\n  /**\r\n   * Group logs by\r\n   * Please note that the order matters here\r\n   * For example, if you set `groupBy: ['level', 'module']`, the logs will be added in level name first, then by module\r\n   *\r\n   * @default none\r\n   */\r\n  groupBy?: (\"level\" | \"module\" | \"action\")[];\r\n  /**\r\n   * Define what levels should be logged\r\n   *\r\n   * @default all\r\n   */\r\n  levels?: LogLevel[];\r\n  /**\r\n   * Date and time format\r\n   */\r\n  dateFormat?: {\r\n    date?: string;\r\n    time?: string;\r\n  };\r\n};\r\n\r\nexport class FileLog extends LogChannel<FileLogConfig> implements LogContract {\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public name = \"file\";\r\n\r\n  /**\r\n   * Messages buffer\r\n   */\r\n  protected messages: LogMessage[] = [];\r\n\r\n  /**\r\n   * Grouped messages\r\n   */\r\n  protected groupedMessages: Record<string, LogMessage[]> = {};\r\n\r\n  /**\r\n   * Default channel configurations\r\n   */\r\n  protected defaultConfigurations: FileLogConfig = {\r\n    storagePath: process.cwd() + \"/storage/logs\",\r\n    rotate: true,\r\n    name: \"app\",\r\n    extension: \"log\",\r\n    chunk: \"single\",\r\n    maxMessagesToWrite: 100,\r\n    filter: () => true,\r\n    maxFileSize: 10 * 1024 * 1024, // 10MB\r\n    get rotateFileName() {\r\n      return dayjs().format(\"DD-MM-YYYY\");\r\n    },\r\n    dateFormat: {\r\n      date: \"DD-MM-YYYY\",\r\n      time: \"HH:mm:ss\",\r\n    },\r\n  };\r\n\r\n  /**\r\n   * Last write time\r\n   */\r\n  protected lastWriteTime = Date.now();\r\n\r\n  /**\r\n   * A flag to determine if the file is being written\r\n   */\r\n  protected isWriting = false;\r\n\r\n  /**\r\n   * Handle for the periodic flush interval. Stored so it can be cleared\r\n   * in `dispose()` — long-lived processes that create channels dynamically\r\n   * would otherwise leak one timer per channel.\r\n   */\r\n  protected flushIntervalHandle?: NodeJS.Timeout;\r\n\r\n  /**\r\n   * Check file size for file rotation\r\n   */\r\n  protected async checkAndRotateFile(filePath = this.filePath) {\r\n    if (!this.config(\"rotate\")) return;\r\n\r\n    try {\r\n      const stats = await fs.promises.stat(filePath);\r\n      if (stats.size >= this.config(\"maxFileSize\")!) {\r\n        await this.rotateLogFile();\r\n      }\r\n    } catch (error: any) {\r\n      // ENOENT is expected when the file hasn't been created yet — there is\r\n      // nothing to rotate, so stay silent. Surface anything else.\r\n      if (error.code !== \"ENOENT\") {\r\n        console.error(\"Error checking log file:\", error);\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Rotate log file\r\n   */\r\n  protected async rotateLogFile() {\r\n    const fileName = `${this.fileName}-${this.config(\"rotateFileName\")}-${Date.now()}`;\r\n\r\n    const extension = this.extension;\r\n\r\n    const rotatedFilePath = path.join(this.storagePath, `${fileName}.${extension}`);\r\n\r\n    await fs.promises.rename(this.filePath, rotatedFilePath).catch((error) => {\r\n      console.error(\"Error rotating file:\", error);\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Flush messages\r\n   *\r\n   * Starts a periodic re-check so low-traffic channels don't sit on buffered\r\n   * entries indefinitely. The handle is stored on the instance so `dispose()`\r\n   * can stop it — without this, every channel leaks a timer for the lifetime\r\n   * of the process.\r\n   */\r\n  protected initMessageFlush() {\r\n    this.flushIntervalHandle = setInterval(() => {\r\n      if (\r\n        this.messages.length > 0 &&\r\n        (this.messages.length >= this.maxMessagesToWrite || Date.now() - this.lastWriteTime > 5000)\r\n      ) {\r\n        this.writeMessagesToFile();\r\n      }\r\n    }, 5000);\r\n  }\r\n\r\n  /**\r\n   * Stop the background flush interval and drain any buffered entries.\r\n   *\r\n   * Call this when discarding a channel (e.g. reconfiguring the logger at\r\n   * runtime) so the 5-second timer doesn't keep the event loop alive. Safe to\r\n   * call more than once.\r\n   */\r\n  public dispose(): void {\r\n    if (this.flushIntervalHandle) {\r\n      clearInterval(this.flushIntervalHandle);\r\n      this.flushIntervalHandle = undefined;\r\n    }\r\n\r\n    this.flushSync();\r\n  }\r\n\r\n  /**\r\n   * Get file path\r\n   */\r\n  public get filePath() {\r\n    const fileName = this.fileName;\r\n\r\n    const extension = this.extension;\r\n\r\n    return path.join(this.storagePath, `${fileName}.${extension}`);\r\n  }\r\n\r\n  /**\r\n   * Get max messages\r\n   */\r\n  protected get maxMessagesToWrite(): number {\r\n    return this.config(\"maxMessagesToWrite\")!;\r\n  }\r\n\r\n  /**\r\n   * Get file name\r\n   */\r\n  public get fileName(): string {\r\n    const debugLevel = this.config(\"chunk\")!;\r\n\r\n    switch (debugLevel) {\r\n      case \"single\":\r\n      default:\r\n        return this.config(\"name\")!;\r\n      case \"daily\":\r\n        return dayjs().format(\"DD-MM-YYYY\");\r\n      case \"hourly\":\r\n        return dayjs().format(\"DD-MM-YYYY-HH-00-00-a\");\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get file extension\r\n   */\r\n  public get extension(): string {\r\n    return this.config(\"extension\")!;\r\n  }\r\n\r\n  /**\r\n   * Get content\r\n   */\r\n  protected get content() {\r\n    return this.messages.map((message) => message.content).join(EOL) + EOL;\r\n  }\r\n\r\n  /**\r\n   * Get storage path\r\n   */\r\n  public get storagePath(): string {\r\n    return this.config(\"storagePath\")!;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  protected async init() {\r\n    const logsDirectory = this.storagePath;\r\n\r\n    await ensureDirectoryAsync(logsDirectory);\r\n\r\n    this.initMessageFlush();\r\n  }\r\n\r\n  /**\r\n   * Synchronously flush messages\r\n   */\r\n  public flushSync(): void {\r\n    if (this.messages.length === 0 && Object.keys(this.groupedMessages).length === 0) return;\r\n\r\n    if (this.messagedShouldBeGrouped) {\r\n      this.prepareGroupedMessages();\r\n      for (const key in this.groupedMessages) {\r\n        const directoryPath = path.join(this.storagePath, key);\r\n        fs.mkdirSync(directoryPath, { recursive: true });\r\n        const filePath = path.join(directoryPath, `${this.fileName}.${this.extension}`);\r\n        const content = this.groupedMessages[key].map((message) => message.content).join(EOL) + EOL;\r\n        fs.appendFileSync(filePath, content);\r\n      }\r\n    } else {\r\n      fs.mkdirSync(this.storagePath, { recursive: true });\r\n      fs.appendFileSync(this.filePath, this.content);\r\n    }\r\n\r\n    this.onSave();\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async log(data: LoggingData) {\r\n    const { module, action, message, type: level, context } = data;\r\n\r\n    if (!this.shouldBeLogged(data)) return;\r\n\r\n    const { date: dateFormat, time } = this.getDateAndTimeFormat();\r\n\r\n    const date = dayjs().format(dateFormat + \" \" + time);\r\n\r\n    let content = `[${date}] [${level}] [${module}][${action}]: `;\r\n\r\n    let stack: string | undefined;\r\n\r\n    // check if message is an instance of Error\r\n    if (message instanceof Error) {\r\n      // in that case we need to store the error message and stack trace\r\n      content += message.message + EOL;\r\n      content += `[trace]` + EOL;\r\n      content += message.stack;\r\n      stack = message.stack;\r\n    } else {\r\n      content += message;\r\n    }\r\n\r\n    this.messages.push({\r\n      content,\r\n      level,\r\n      date,\r\n      module,\r\n      action,\r\n      stack,\r\n      context,\r\n      timestamp: new Date().toISOString(),\r\n    });\r\n\r\n    await this.checkIfMessagesShouldBeWritten(); // Immediate check on buffer size\r\n  }\r\n\r\n  /**\r\n   * Check if messages should be written\r\n   */\r\n  protected async checkIfMessagesShouldBeWritten() {\r\n    if (this.messages.length >= this.maxMessagesToWrite || Date.now() - this.lastWriteTime > 5000) {\r\n      await this.writeMessagesToFile();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Should be called after messages are saved\r\n   */\r\n  protected onSave() {\r\n    this.messages = [];\r\n    this.groupedMessages = {};\r\n    this.isWriting = false;\r\n    this.lastWriteTime = Date.now();\r\n  }\r\n\r\n  /**\r\n   * Check if messages should be grouped\r\n   */\r\n  protected get messagedShouldBeGrouped(): boolean {\r\n    return Number(this.config(\"groupBy\")?.length) > 0;\r\n  }\r\n\r\n  /**\r\n   * Write messages to the file\r\n   */\r\n  protected async writeMessagesToFile() {\r\n    if (this.messages.length === 0 || this.isWriting || !this.isInitialized) return;\r\n\r\n    this.isWriting = true;\r\n\r\n    if (this.messagedShouldBeGrouped) {\r\n      return await this.writeGroupedMessagesToFile();\r\n    }\r\n\r\n    await this.checkAndRotateFile(); // Ensure we check file size before writing\r\n\r\n    try {\r\n      await this.write(this.filePath, this.content);\r\n      this.onSave();\r\n    } catch (error) {\r\n      console.error(\"Failed to write log:\", error);\r\n      // Implement fallback logic here\r\n      this.isWriting = false;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Write grouped messages to the file\r\n   */\r\n  protected async writeGroupedMessagesToFile(): Promise<void> {\r\n    // first step, is to group the messages\r\n    this.prepareGroupedMessages();\r\n\r\n    // now each key in the grouped messages, represents the directory path that should extend the storage path\r\n    for (const key in this.groupedMessages) {\r\n      const directoryPath = path.join(this.storagePath, key);\r\n\r\n      await ensureDirectoryAsync(directoryPath);\r\n\r\n      const filePath = path.join(directoryPath, `${this.fileName}.${this.extension}`);\r\n\r\n      await this.checkAndRotateFile(filePath); // Ensure we check file size before writing\r\n\r\n      const content = this.groupedMessages[key].map((message) => message.content).join(EOL) + EOL;\r\n\r\n      try {\r\n        await this.write(filePath, content);\r\n      } catch (error) {\r\n        console.error(\"Failed to write log:\", error);\r\n      }\r\n    }\r\n\r\n    this.onSave();\r\n    this.isWriting = false;\r\n  }\r\n\r\n  /**\r\n   * Prepare grouped messages\r\n   */\r\n  protected prepareGroupedMessages(): void {\r\n    this.messages.forEach((message) => {\r\n      const key = this.config(\"groupBy\")!\r\n        .map((groupKey) => encodeURIComponent(message[groupKey]))\r\n        .join(\"/\");\r\n\r\n      this.groupedMessages[key] = this.groupedMessages[key] || [];\r\n      this.groupedMessages[key].push(message);\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Start writing to the file\r\n   */\r\n  protected async write(filePath: string, content: string) {\r\n    return new Promise((resolve, reject) => {\r\n      const writer = fs.createWriteStream(filePath, { flags: \"a\" });\r\n\r\n      writer.write(content, (error) => {\r\n        writer.end();\r\n        if (error) {\r\n          reject(error);\r\n        } else {\r\n          resolve(true);\r\n        }\r\n      });\r\n    });\r\n  }\r\n}\r\n"],"mappings":"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"}
+{"version":3,"file":"file-log.mjs","names":[],"sources":["../../../../../../../@warlock.js/logger/src/channels/file-log.ts"],"sourcesContent":["import { ensureDirectoryAsync } from \"@warlock.js/fs\";\r\nimport dayjs from \"dayjs\";\r\nimport fs from \"fs\";\r\nimport { EOL } from \"os\";\r\nimport path from \"path\";\r\nimport { LogChannel } from \"../log-channel\";\r\nimport type {\r\n  BasicLogConfigurations,\r\n  LogContract,\r\n  LoggingData,\r\n  LogLevel,\r\n  LogMessage,\r\n} from \"../types\";\r\n\r\n// TODO: Add max messages per file before rotation\r\n\r\nexport type FileLogConfig = BasicLogConfigurations & {\r\n  storagePath?: string;\r\n  /**\r\n   * File name, without extension\r\n   */\r\n  name?: string;\r\n  /**\r\n   * chunk mode\r\n   * If set to `single`, the logs will be created in a single file, unless the rotate is set to true\r\n   * If set to `daily`, the logs will be created in a daily file, unless the rotate is set to true\r\n   * If set to `hourly`, the logs will be created in an hourly file, unless the rotate is set to true\r\n   * @default single\r\n   */\r\n  chunk?: \"single\" | \"daily\" | \"hourly\";\r\n  /**\r\n   * Whether to rotate the file\r\n   *\r\n   * @default true\r\n   */\r\n  rotate?: boolean;\r\n  /**\r\n   * File Extension\r\n   *\r\n   * @default log\r\n   */\r\n  extension?: string;\r\n  /**\r\n   * If rotate is set, the rotate name will be added to the file name suffixed with `-`\r\n   *\r\n   * @default DD-MM-YYYY\r\n   */\r\n  rotateFileName?: string;\r\n  /**\r\n   * Max file size before rotating the file\r\n   *\r\n   * @default 10MB\r\n   */\r\n  maxFileSize?: number;\r\n  /**\r\n   * Set the max messages that needs to be added before writing to the file\r\n   *\r\n   * @default 100\r\n   */\r\n  maxMessagesToWrite?: number;\r\n  /**\r\n   * Group logs by\r\n   * Please note that the order matters here\r\n   * For example, if you set `groupBy: ['level', 'module']`, the logs will be added in level name first, then by module\r\n   *\r\n   * @default none\r\n   */\r\n  groupBy?: (\"level\" | \"module\" | \"action\")[];\r\n  /**\r\n   * Define what levels should be logged\r\n   *\r\n   * @default all\r\n   */\r\n  levels?: LogLevel[];\r\n  /**\r\n   * Date and time format\r\n   */\r\n  dateFormat?: {\r\n    date?: string;\r\n    time?: string;\r\n  };\r\n};\r\n\r\nexport class FileLog extends LogChannel<FileLogConfig> implements LogContract {\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public name = \"file\";\r\n\r\n  /**\r\n   * Messages buffer\r\n   */\r\n  protected messages: LogMessage[] = [];\r\n\r\n  /**\r\n   * Grouped messages\r\n   */\r\n  protected groupedMessages: Record<string, LogMessage[]> = {};\r\n\r\n  /**\r\n   * Default channel configurations\r\n   */\r\n  protected defaultConfigurations: FileLogConfig = {\r\n    storagePath: process.cwd() + \"/storage/logs\",\r\n    rotate: true,\r\n    name: \"app\",\r\n    extension: \"log\",\r\n    chunk: \"single\",\r\n    maxMessagesToWrite: 100,\r\n    filter: () => true,\r\n    maxFileSize: 10 * 1024 * 1024, // 10MB\r\n    get rotateFileName() {\r\n      return dayjs().format(\"DD-MM-YYYY\");\r\n    },\r\n    dateFormat: {\r\n      date: \"DD-MM-YYYY\",\r\n      time: \"HH:mm:ss\",\r\n    },\r\n  };\r\n\r\n  /**\r\n   * Last write time\r\n   */\r\n  protected lastWriteTime = Date.now();\r\n\r\n  /**\r\n   * A flag to determine if the file is being written\r\n   */\r\n  protected isWriting = false;\r\n\r\n  /**\r\n   * Handle for the periodic flush interval. Stored so it can be cleared\r\n   * in `dispose()` — long-lived processes that create channels dynamically\r\n   * would otherwise leak one timer per channel.\r\n   */\r\n  protected flushIntervalHandle?: NodeJS.Timeout;\r\n\r\n  /**\r\n   * Check file size for file rotation\r\n   */\r\n  protected async checkAndRotateFile(filePath = this.filePath) {\r\n    if (!this.config(\"rotate\")) return;\r\n\r\n    try {\r\n      const stats = await fs.promises.stat(filePath);\r\n      if (stats.size >= this.config(\"maxFileSize\")!) {\r\n        await this.rotateLogFile();\r\n      }\r\n    } catch (error: any) {\r\n      // ENOENT is expected when the file hasn't been created yet — there is\r\n      // nothing to rotate, so stay silent. Surface anything else.\r\n      if (error.code !== \"ENOENT\") {\r\n        console.error(\"Error checking log file:\", error);\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Rotate log file\r\n   */\r\n  protected async rotateLogFile() {\r\n    const fileName = `${this.fileName}-${this.config(\"rotateFileName\")}-${Date.now()}`;\r\n\r\n    const extension = this.extension;\r\n\r\n    const rotatedFilePath = path.join(this.storagePath, `${fileName}.${extension}`);\r\n\r\n    await fs.promises.rename(this.filePath, rotatedFilePath).catch((error) => {\r\n      console.error(\"Error rotating file:\", error);\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Flush messages\r\n   *\r\n   * Starts a periodic re-check so low-traffic channels don't sit on buffered\r\n   * entries indefinitely. The handle is stored on the instance so `dispose()`\r\n   * can stop it — without this, every channel leaks a timer for the lifetime\r\n   * of the process.\r\n   */\r\n  protected initMessageFlush() {\r\n    this.flushIntervalHandle = setInterval(() => {\r\n      if (\r\n        this.messages.length > 0 &&\r\n        (this.messages.length >= this.maxMessagesToWrite || Date.now() - this.lastWriteTime > 5000)\r\n      ) {\r\n        this.writeMessagesToFile();\r\n      }\r\n    }, 5000);\r\n  }\r\n\r\n  /**\r\n   * Stop the background flush interval and drain any buffered entries.\r\n   *\r\n   * Call this when discarding a channel (e.g. reconfiguring the logger at\r\n   * runtime) so the 5-second timer doesn't keep the event loop alive. Safe to\r\n   * call more than once.\r\n   */\r\n  public dispose(): void {\r\n    if (this.flushIntervalHandle) {\r\n      clearInterval(this.flushIntervalHandle);\r\n      this.flushIntervalHandle = undefined;\r\n    }\r\n\r\n    this.flushSync();\r\n  }\r\n\r\n  /**\r\n   * Get file path\r\n   */\r\n  public get filePath() {\r\n    const fileName = this.fileName;\r\n\r\n    const extension = this.extension;\r\n\r\n    return path.join(this.storagePath, `${fileName}.${extension}`);\r\n  }\r\n\r\n  /**\r\n   * Get max messages\r\n   */\r\n  protected get maxMessagesToWrite(): number {\r\n    return this.config(\"maxMessagesToWrite\")!;\r\n  }\r\n\r\n  /**\r\n   * Get file name\r\n   */\r\n  public get fileName(): string {\r\n    const debugLevel = this.config(\"chunk\")!;\r\n\r\n    switch (debugLevel) {\r\n      case \"single\":\r\n      default:\r\n        return this.config(\"name\")!;\r\n      case \"daily\":\r\n        return dayjs().format(\"DD-MM-YYYY\");\r\n      case \"hourly\":\r\n        return dayjs().format(\"DD-MM-YYYY-HH-00-00-a\");\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get file extension\r\n   */\r\n  public get extension(): string {\r\n    return this.config(\"extension\")!;\r\n  }\r\n\r\n  /**\r\n   * Get content\r\n   */\r\n  protected get content() {\r\n    return this.messages.map((message) => message.content).join(EOL) + EOL;\r\n  }\r\n\r\n  /**\r\n   * Get storage path\r\n   */\r\n  public get storagePath(): string {\r\n    return this.config(\"storagePath\")!;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  protected async init() {\r\n    const logsDirectory = this.storagePath;\r\n\r\n    await ensureDirectoryAsync(logsDirectory);\r\n\r\n    this.initMessageFlush();\r\n  }\r\n\r\n  /**\r\n   * Synchronously flush messages\r\n   */\r\n  public flushSync(): void {\r\n    if (this.messages.length === 0 && Object.keys(this.groupedMessages).length === 0) return;\r\n\r\n    if (this.messagedShouldBeGrouped) {\r\n      this.prepareGroupedMessages();\r\n      for (const key in this.groupedMessages) {\r\n        const directoryPath = path.join(this.storagePath, key);\r\n        fs.mkdirSync(directoryPath, { recursive: true });\r\n        const filePath = path.join(directoryPath, `${this.fileName}.${this.extension}`);\r\n        const content = this.groupedMessages[key].map((message) => message.content).join(EOL) + EOL;\r\n        fs.appendFileSync(filePath, content);\r\n      }\r\n    } else {\r\n      fs.mkdirSync(this.storagePath, { recursive: true });\r\n      fs.appendFileSync(this.filePath, this.content);\r\n    }\r\n\r\n    this.onSave();\r\n  }\r\n\r\n  /**\r\n   * Asynchronously drain buffered entries to disk.\r\n   *\r\n   * The async analogue of {@link flushSync}: it reuses the same async writer\r\n   * as the background interval, so a caller on a graceful-shutdown path can\r\n   * `await channel.flush()` (or `await log.flush()`) and rely on the buffer\r\n   * being on disk once it resolves. `JSONFileLog` inherits this unchanged —\r\n   * its overridden `writeMessagesToFile` performs the JSON merge.\r\n   */\r\n  public async flush(): Promise<void> {\r\n    if (this.messages.length === 0 && Object.keys(this.groupedMessages).length === 0) {\r\n      return;\r\n    }\r\n\r\n    // Clear the in-flight lock so a deliberate drain is never short-circuited\r\n    // by a half-finished background write, then await the async writer to\r\n    // completion — unlike the fire-and-forget interval, callers depend on the\r\n    // buffer reaching disk before this resolves.\r\n    this.isWriting = false;\r\n\r\n    await this.writeMessagesToFile();\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async log(data: LoggingData) {\r\n    const { module, action, message, type: level, context } = data;\r\n\r\n    if (!this.shouldBeLogged(data)) return;\r\n\r\n    const { date: dateFormat, time } = this.getDateAndTimeFormat();\r\n\r\n    const date = dayjs().format(dateFormat + \" \" + time);\r\n\r\n    let content = `[${date}] [${level}] [${module}][${action}]: `;\r\n\r\n    let stack: string | undefined;\r\n\r\n    // check if message is an instance of Error\r\n    if (message instanceof Error) {\r\n      // in that case we need to store the error message and stack trace\r\n      content += message.message + EOL;\r\n      content += `[trace]` + EOL;\r\n      content += message.stack;\r\n      stack = message.stack;\r\n    } else {\r\n      content += message;\r\n    }\r\n\r\n    this.messages.push({\r\n      content,\r\n      level,\r\n      date,\r\n      module,\r\n      action,\r\n      stack,\r\n      context,\r\n      timestamp: new Date().toISOString(),\r\n    });\r\n\r\n    await this.checkIfMessagesShouldBeWritten(); // Immediate check on buffer size\r\n  }\r\n\r\n  /**\r\n   * Check if messages should be written\r\n   */\r\n  protected async checkIfMessagesShouldBeWritten() {\r\n    if (this.messages.length >= this.maxMessagesToWrite || Date.now() - this.lastWriteTime > 5000) {\r\n      await this.writeMessagesToFile();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Should be called after messages are saved\r\n   */\r\n  protected onSave() {\r\n    this.messages = [];\r\n    this.groupedMessages = {};\r\n    this.isWriting = false;\r\n    this.lastWriteTime = Date.now();\r\n  }\r\n\r\n  /**\r\n   * Check if messages should be grouped\r\n   */\r\n  protected get messagedShouldBeGrouped(): boolean {\r\n    return Number(this.config(\"groupBy\")?.length) > 0;\r\n  }\r\n\r\n  /**\r\n   * Write messages to the file\r\n   */\r\n  protected async writeMessagesToFile() {\r\n    if (this.messages.length === 0 || this.isWriting || !this.isInitialized) return;\r\n\r\n    this.isWriting = true;\r\n\r\n    if (this.messagedShouldBeGrouped) {\r\n      return await this.writeGroupedMessagesToFile();\r\n    }\r\n\r\n    await this.checkAndRotateFile(); // Ensure we check file size before writing\r\n\r\n    try {\r\n      await this.write(this.filePath, this.content);\r\n      this.onSave();\r\n    } catch (error) {\r\n      console.error(\"Failed to write log:\", error);\r\n      // Implement fallback logic here\r\n      this.isWriting = false;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Write grouped messages to the file\r\n   */\r\n  protected async writeGroupedMessagesToFile(): Promise<void> {\r\n    // first step, is to group the messages\r\n    this.prepareGroupedMessages();\r\n\r\n    // now each key in the grouped messages, represents the directory path that should extend the storage path\r\n    for (const key in this.groupedMessages) {\r\n      const directoryPath = path.join(this.storagePath, key);\r\n\r\n      await ensureDirectoryAsync(directoryPath);\r\n\r\n      const filePath = path.join(directoryPath, `${this.fileName}.${this.extension}`);\r\n\r\n      await this.checkAndRotateFile(filePath); // Ensure we check file size before writing\r\n\r\n      const content = this.groupedMessages[key].map((message) => message.content).join(EOL) + EOL;\r\n\r\n      try {\r\n        await this.write(filePath, content);\r\n      } catch (error) {\r\n        console.error(\"Failed to write log:\", error);\r\n      }\r\n    }\r\n\r\n    this.onSave();\r\n    this.isWriting = false;\r\n  }\r\n\r\n  /**\r\n   * Prepare grouped messages\r\n   */\r\n  protected prepareGroupedMessages(): void {\r\n    this.messages.forEach((message) => {\r\n      const key = this.config(\"groupBy\")!\r\n        .map((groupKey) => encodeURIComponent(message[groupKey]))\r\n        .join(\"/\");\r\n\r\n      this.groupedMessages[key] = this.groupedMessages[key] || [];\r\n      this.groupedMessages[key].push(message);\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Start writing to the file\r\n   */\r\n  protected async write(filePath: string, content: string) {\r\n    return new Promise((resolve, reject) => {\r\n      const writer = fs.createWriteStream(filePath, { flags: \"a\" });\r\n\r\n      writer.write(content, (error) => {\r\n        writer.end();\r\n        if (error) {\r\n          reject(error);\r\n        } else {\r\n          resolve(true);\r\n        }\r\n      });\r\n    });\r\n  }\r\n}\r\n"],"mappings":"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"}

package/esm/channels/index.mjs

@@ -1,5 +1,6 @@
 import { ConsoleLog } from "./console-log.mjs";
 import { FileLog } from "./file-log.mjs";
 import { JSONFileLog } from "./json-file-log.mjs";
+import { SentryLog } from "./sentry-log.mjs";
 
 export {  };

package/esm/channels/json-file-log.d.mts

@@ -1,7 +1,7 @@
 import { LogContract, LoggingData } from "../types.mjs";
 import { FileLog } from "./file-log.mjs";
 
-//#region ../../@warlock.js/logger/src/channels/json-file-log.d.ts
+//#region ../@warlock.js/logger/src/channels/json-file-log.d.ts
 declare class JSONFileLog extends FileLog implements LogContract {
   /**
    * {@inheritdoc}

package/esm/channels/json-file-log.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"json-file-log.d.mts","names":[],"sources":["../../../../../../@warlock.js/logger/src/channels/json-file-log.ts"],"mappings":";;;;cAQa,WAAA,SAAoB,OAAA,YAAmB,WAAA;;AAApD;;EAIS,IAAA;EAuDgB;;;EAAA,IAlDZ,SAAA,CAAA;EAToB;;;EAgBxB,SAAA,CAAA;EAhBwB;;;EA2DlB,GAAA,CAAI,IAAA,EAAM,WAAA,GAAW,OAAA;EA3C3B;;;EAAA,UA4ES,mBAAA,CAAA,GAAuB,OAAA;EAjCL;;;EAAA,UAyElB,0BAAA,CAAA,GAA8B,OAAA;AAAA"}
+{"version":3,"file":"json-file-log.d.mts","names":[],"sources":["../../../../../../../@warlock.js/logger/src/channels/json-file-log.ts"],"mappings":";;;;cAQa,WAAA,SAAoB,OAAA,YAAmB,WAAA;;AAApD;;EAIS,IAAA;EAuDgB;;;EAAA,IAlDZ,SAAA;EAToB;;;EAgBxB,SAAA;EAhBwB;;;EA2DlB,GAAA,CAAI,IAAA,EAAM,WAAA,GAAW,OAAA;EA3C3B;;;EAAA,UA4ES,mBAAA,IAAuB,OAAA;EAjCL;;;EAAA,UAyElB,0BAAA,IAA8B,OAAA;AAAA"}

package/esm/channels/json-file-log.mjs

@@ -5,7 +5,7 @@ import dayjs from "dayjs";
 import fs from "fs";
 import path from "path";
 
-//#region ../../@warlock.js/logger/src/channels/json-file-log.ts
+//#region ../@warlock.js/logger/src/channels/json-file-log.ts
 var JSONFileLog = class extends FileLog {
 	constructor(..._args) {
 		super(..._args);

package/esm/channels/json-file-log.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"json-file-log.mjs","names":[],"sources":["../../../../../../@warlock.js/logger/src/channels/json-file-log.ts"],"sourcesContent":["import { ensureDirectoryAsync, fileExistsAsync, getJsonFileAsync } from \"@warlock.js/fs\";\r\nimport dayjs from \"dayjs\";\r\nimport fs from \"fs\";\r\nimport path from \"path\";\r\nimport type { LogContract, LogMessage, LoggingData } from \"../types\";\r\nimport { safeJsonStringify } from \"../utils/safe-json-stringify\";\r\nimport { FileLog } from \"./file-log\";\r\n\r\nexport class JSONFileLog extends FileLog implements LogContract {\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public name = \"fileJson\";\r\n\r\n  /**\r\n   * Get file extension\r\n   */\r\n  public get extension(): string {\r\n    return \"json\";\r\n  }\r\n\r\n  /**\r\n   * Synchronously flush messages\r\n   */\r\n  public flushSync(): void {\r\n    if (this.messages.length === 0 && Object.keys(this.groupedMessages).length === 0) return;\r\n\r\n    if (this.messagedShouldBeGrouped) {\r\n      this.prepareGroupedMessages();\r\n      for (const key in this.groupedMessages) {\r\n        const directoryPath = path.join(this.storagePath, key);\r\n        fs.mkdirSync(directoryPath, { recursive: true });\r\n        const filePath = path.join(directoryPath, `${this.fileName}.${this.extension}`);\r\n\r\n        let fileContents = { messages: [] as any[] };\r\n        if (fs.existsSync(filePath)) {\r\n          try {\r\n            fileContents = JSON.parse(fs.readFileSync(filePath, \"utf-8\"));\r\n            if (!Array.isArray(fileContents.messages)) fileContents.messages = [];\r\n          } catch (e) {\r\n            fileContents = { messages: [] };\r\n          }\r\n        }\r\n        fileContents.messages.push(...this.groupedMessages[key]);\r\n        fs.writeFileSync(filePath, safeJsonStringify(fileContents, 2));\r\n      }\r\n    } else {\r\n      fs.mkdirSync(this.storagePath, { recursive: true });\r\n      let fileContents = { messages: [] as any[] };\r\n      if (fs.existsSync(this.filePath)) {\r\n        try {\r\n          fileContents = JSON.parse(fs.readFileSync(this.filePath, \"utf-8\"));\r\n          if (!Array.isArray(fileContents.messages)) fileContents.messages = [];\r\n        } catch (e) {\r\n          fileContents = { messages: [] };\r\n        }\r\n      }\r\n      fileContents.messages.push(...this.messages);\r\n      fs.writeFileSync(this.filePath, safeJsonStringify(fileContents, 2));\r\n    }\r\n\r\n    this.onSave();\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async log(data: LoggingData) {\r\n    let stack: string[] | undefined;\r\n\r\n    if (data.message instanceof Error) {\r\n      stack = data.message.stack?.split(\"\\n\");\r\n      data.message = data.message.message;\r\n    }\r\n\r\n    const { module, action, message, type: level, context } = data;\r\n\r\n    if (!this.shouldBeLogged(data)) return;\r\n\r\n    const { date: dateFormat, time } = this.getDateAndTimeFormat();\r\n\r\n    const date = dayjs().format(dateFormat + \" \" + time);\r\n\r\n    this.messages.push({\r\n      content: message,\r\n      level,\r\n      date,\r\n      module,\r\n      action,\r\n      stack,\r\n      context,\r\n      timestamp: new Date().toISOString(),\r\n    } as LogMessage);\r\n\r\n    await this.checkIfMessagesShouldBeWritten(); // Immediate check on buffer size\r\n  }\r\n\r\n  /**\r\n   * Write messages to the file\r\n   */\r\n  protected async writeMessagesToFile(): Promise<void> {\r\n    if (this.messages.length === 0 || this.isWriting || !this.isInitialized) return;\r\n\r\n    this.isWriting = true;\r\n\r\n    if (this.messagedShouldBeGrouped) {\r\n      return await this.writeGroupedMessagesToFile();\r\n    }\r\n\r\n    await this.checkAndRotateFile(); // Ensure file rotation is handled\r\n\r\n    let fileContents = { messages: [] as any[] };\r\n\r\n    if (await fileExistsAsync(this.filePath)) {\r\n      try {\r\n        fileContents = (await getJsonFileAsync(this.filePath)) as { messages: any[] };\r\n      } catch (error) {\r\n        console.error(\"Error reading log file, reinitializing:\", error);\r\n        fileContents = { messages: [] }; // Reinitialize the file if corrupted\r\n      }\r\n    } else {\r\n      fileContents = { messages: [] }; // Reinitialize the file if corrupted\r\n    }\r\n\r\n    fileContents.messages.push(...this.messages);\r\n\r\n    try {\r\n      await fs.promises.writeFile(this.filePath, safeJsonStringify(fileContents, 2));\r\n\r\n      this.onSave();\r\n    } catch (error) {\r\n      console.error(\"Failed to write log:\", error);\r\n      // Implement fallback logic here\r\n      this.isWriting = false;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Write grouped messages to the file\r\n   */\r\n  protected async writeGroupedMessagesToFile(): Promise<void> {\r\n    // first step, is to group the messages\r\n    this.prepareGroupedMessages();\r\n\r\n    // now each key in the grouped messages, represents the directory path that should extend the storage path\r\n    for (const key in this.groupedMessages) {\r\n      const directoryPath = path.join(this.storagePath, key);\r\n\r\n      await ensureDirectoryAsync(directoryPath);\r\n\r\n      const filePath = path.join(directoryPath, `${this.fileName}.${this.extension}`);\r\n\r\n      await this.checkAndRotateFile(filePath); // Ensure we check file size before writing\r\n\r\n      let fileContents: { messages: any[] } = { messages: [] };\r\n      if (await fileExistsAsync(filePath)) {\r\n        try {\r\n          fileContents = (await getJsonFileAsync(filePath)) as { messages: any[] };\r\n        } catch (error) {\r\n          console.error(\"Error reading log file, reinitializing:\", error);\r\n          fileContents = { messages: [] };\r\n        }\r\n      } else {\r\n        fileContents = { messages: [] };\r\n      }\r\n\r\n      fileContents.messages.push(...this.groupedMessages[key]);\r\n\r\n      try {\r\n        await fs.promises.writeFile(filePath, safeJsonStringify(fileContents, 2));\r\n      } catch (error) {\r\n        console.error(\"Failed to write log:\", error);\r\n        this.isWriting = false;\r\n      }\r\n    }\r\n\r\n    this.onSave();\r\n  }\r\n}\r\n"],"mappings":"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"}
+{"version":3,"file":"json-file-log.mjs","names":[],"sources":["../../../../../../../@warlock.js/logger/src/channels/json-file-log.ts"],"sourcesContent":["import { ensureDirectoryAsync, fileExistsAsync, getJsonFileAsync } from \"@warlock.js/fs\";\r\nimport dayjs from \"dayjs\";\r\nimport fs from \"fs\";\r\nimport path from \"path\";\r\nimport type { LogContract, LogMessage, LoggingData } from \"../types\";\r\nimport { safeJsonStringify } from \"../utils/safe-json-stringify\";\r\nimport { FileLog } from \"./file-log\";\r\n\r\nexport class JSONFileLog extends FileLog implements LogContract {\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public name = \"fileJson\";\r\n\r\n  /**\r\n   * Get file extension\r\n   */\r\n  public get extension(): string {\r\n    return \"json\";\r\n  }\r\n\r\n  /**\r\n   * Synchronously flush messages\r\n   */\r\n  public flushSync(): void {\r\n    if (this.messages.length === 0 && Object.keys(this.groupedMessages).length === 0) return;\r\n\r\n    if (this.messagedShouldBeGrouped) {\r\n      this.prepareGroupedMessages();\r\n      for (const key in this.groupedMessages) {\r\n        const directoryPath = path.join(this.storagePath, key);\r\n        fs.mkdirSync(directoryPath, { recursive: true });\r\n        const filePath = path.join(directoryPath, `${this.fileName}.${this.extension}`);\r\n\r\n        let fileContents = { messages: [] as any[] };\r\n        if (fs.existsSync(filePath)) {\r\n          try {\r\n            fileContents = JSON.parse(fs.readFileSync(filePath, \"utf-8\"));\r\n            if (!Array.isArray(fileContents.messages)) fileContents.messages = [];\r\n          } catch (e) {\r\n            fileContents = { messages: [] };\r\n          }\r\n        }\r\n        fileContents.messages.push(...this.groupedMessages[key]);\r\n        fs.writeFileSync(filePath, safeJsonStringify(fileContents, 2));\r\n      }\r\n    } else {\r\n      fs.mkdirSync(this.storagePath, { recursive: true });\r\n      let fileContents = { messages: [] as any[] };\r\n      if (fs.existsSync(this.filePath)) {\r\n        try {\r\n          fileContents = JSON.parse(fs.readFileSync(this.filePath, \"utf-8\"));\r\n          if (!Array.isArray(fileContents.messages)) fileContents.messages = [];\r\n        } catch (e) {\r\n          fileContents = { messages: [] };\r\n        }\r\n      }\r\n      fileContents.messages.push(...this.messages);\r\n      fs.writeFileSync(this.filePath, safeJsonStringify(fileContents, 2));\r\n    }\r\n\r\n    this.onSave();\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async log(data: LoggingData) {\r\n    let stack: string[] | undefined;\r\n\r\n    if (data.message instanceof Error) {\r\n      stack = data.message.stack?.split(\"\\n\");\r\n      data.message = data.message.message;\r\n    }\r\n\r\n    const { module, action, message, type: level, context } = data;\r\n\r\n    if (!this.shouldBeLogged(data)) return;\r\n\r\n    const { date: dateFormat, time } = this.getDateAndTimeFormat();\r\n\r\n    const date = dayjs().format(dateFormat + \" \" + time);\r\n\r\n    this.messages.push({\r\n      content: message,\r\n      level,\r\n      date,\r\n      module,\r\n      action,\r\n      stack,\r\n      context,\r\n      timestamp: new Date().toISOString(),\r\n    } as LogMessage);\r\n\r\n    await this.checkIfMessagesShouldBeWritten(); // Immediate check on buffer size\r\n  }\r\n\r\n  /**\r\n   * Write messages to the file\r\n   */\r\n  protected async writeMessagesToFile(): Promise<void> {\r\n    if (this.messages.length === 0 || this.isWriting || !this.isInitialized) return;\r\n\r\n    this.isWriting = true;\r\n\r\n    if (this.messagedShouldBeGrouped) {\r\n      return await this.writeGroupedMessagesToFile();\r\n    }\r\n\r\n    await this.checkAndRotateFile(); // Ensure file rotation is handled\r\n\r\n    let fileContents = { messages: [] as any[] };\r\n\r\n    if (await fileExistsAsync(this.filePath)) {\r\n      try {\r\n        fileContents = (await getJsonFileAsync(this.filePath)) as { messages: any[] };\r\n      } catch (error) {\r\n        console.error(\"Error reading log file, reinitializing:\", error);\r\n        fileContents = { messages: [] }; // Reinitialize the file if corrupted\r\n      }\r\n    } else {\r\n      fileContents = { messages: [] }; // Reinitialize the file if corrupted\r\n    }\r\n\r\n    fileContents.messages.push(...this.messages);\r\n\r\n    try {\r\n      await fs.promises.writeFile(this.filePath, safeJsonStringify(fileContents, 2));\r\n\r\n      this.onSave();\r\n    } catch (error) {\r\n      console.error(\"Failed to write log:\", error);\r\n      // Implement fallback logic here\r\n      this.isWriting = false;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Write grouped messages to the file\r\n   */\r\n  protected async writeGroupedMessagesToFile(): Promise<void> {\r\n    // first step, is to group the messages\r\n    this.prepareGroupedMessages();\r\n\r\n    // now each key in the grouped messages, represents the directory path that should extend the storage path\r\n    for (const key in this.groupedMessages) {\r\n      const directoryPath = path.join(this.storagePath, key);\r\n\r\n      await ensureDirectoryAsync(directoryPath);\r\n\r\n      const filePath = path.join(directoryPath, `${this.fileName}.${this.extension}`);\r\n\r\n      await this.checkAndRotateFile(filePath); // Ensure we check file size before writing\r\n\r\n      let fileContents: { messages: any[] } = { messages: [] };\r\n      if (await fileExistsAsync(filePath)) {\r\n        try {\r\n          fileContents = (await getJsonFileAsync(filePath)) as { messages: any[] };\r\n        } catch (error) {\r\n          console.error(\"Error reading log file, reinitializing:\", error);\r\n          fileContents = { messages: [] };\r\n        }\r\n      } else {\r\n        fileContents = { messages: [] };\r\n      }\r\n\r\n      fileContents.messages.push(...this.groupedMessages[key]);\r\n\r\n      try {\r\n        await fs.promises.writeFile(filePath, safeJsonStringify(fileContents, 2));\r\n      } catch (error) {\r\n        console.error(\"Failed to write log:\", error);\r\n        this.isWriting = false;\r\n      }\r\n    }\r\n\r\n    this.onSave();\r\n  }\r\n}\r\n"],"mappings":";;;;;;;;AAQA,IAAa,cAAb,cAAiC,QAA+B;;;cAIhD;;;;;CAKd,IAAW,YAAoB;EAC7B,OAAO;CACT;;;;CAKA,AAAO,YAAkB;EACvB,IAAI,KAAK,SAAS,WAAW,KAAK,OAAO,KAAK,KAAK,eAAe,CAAC,CAAC,WAAW,GAAG;EAElF,IAAI,KAAK,yBAAyB;GAChC,KAAK,uBAAuB;GAC5B,KAAK,MAAM,OAAO,KAAK,iBAAiB;IACtC,MAAM,gBAAgB,KAAK,KAAK,KAAK,aAAa,GAAG;IACrD,GAAG,UAAU,eAAe,EAAE,WAAW,KAAK,CAAC;IAC/C,MAAM,WAAW,KAAK,KAAK,eAAe,GAAG,KAAK,SAAS,GAAG,KAAK,WAAW;IAE9E,IAAI,eAAe,EAAE,UAAU,CAAC,EAAW;IAC3C,IAAI,GAAG,WAAW,QAAQ,GACxB,IAAI;KACF,eAAe,KAAK,MAAM,GAAG,aAAa,UAAU,OAAO,CAAC;KAC5D,IAAI,CAAC,MAAM,QAAQ,aAAa,QAAQ,GAAG,aAAa,WAAW,CAAC;IACtE,SAAS,GAAG;KACV,eAAe,EAAE,UAAU,CAAC,EAAE;IAChC;IAEF,aAAa,SAAS,KAAK,GAAG,KAAK,gBAAgB,IAAI;IACvD,GAAG,cAAc,UAAU,kBAAkB,cAAc,CAAC,CAAC;GAC/D;EACF,OAAO;GACL,GAAG,UAAU,KAAK,aAAa,EAAE,WAAW,KAAK,CAAC;GAClD,IAAI,eAAe,EAAE,UAAU,CAAC,EAAW;GAC3C,IAAI,GAAG,WAAW,KAAK,QAAQ,GAC7B,IAAI;IACF,eAAe,KAAK,MAAM,GAAG,aAAa,KAAK,UAAU,OAAO,CAAC;IACjE,IAAI,CAAC,MAAM,QAAQ,aAAa,QAAQ,GAAG,aAAa,WAAW,CAAC;GACtE,SAAS,GAAG;IACV,eAAe,EAAE,UAAU,CAAC,EAAE;GAChC;GAEF,aAAa,SAAS,KAAK,GAAG,KAAK,QAAQ;GAC3C,GAAG,cAAc,KAAK,UAAU,kBAAkB,cAAc,CAAC,CAAC;EACpE;EAEA,KAAK,OAAO;CACd;;;;CAKA,MAAa,IAAI,MAAmB;EAClC,IAAI;EAEJ,IAAI,KAAK,mBAAmB,OAAO;GACjC,QAAQ,KAAK,QAAQ,OAAO,MAAM,IAAI;GACtC,KAAK,UAAU,KAAK,QAAQ;EAC9B;EAEA,MAAM,EAAE,QAAQ,QAAQ,SAAS,MAAM,OAAO,YAAY;EAE1D,IAAI,CAAC,KAAK,eAAe,IAAI,GAAG;EAEhC,MAAM,EAAE,MAAM,YAAY,SAAS,KAAK,qBAAqB;EAE7D,MAAM,OAAO,MAAM,CAAC,CAAC,OAAO,aAAa,MAAM,IAAI;EAEnD,KAAK,SAAS,KAAK;GACjB,SAAS;GACT;GACA;GACA;GACA;GACA;GACA;GACA,4BAAW,IAAI,KAAK,EAAC,CAAC,YAAY;EACpC,CAAe;EAEf,MAAM,KAAK,+BAA+B;CAC5C;;;;CAKA,MAAgB,sBAAqC;EACnD,IAAI,KAAK,SAAS,WAAW,KAAK,KAAK,aAAa,CAAC,KAAK,eAAe;EAEzE,KAAK,YAAY;EAEjB,IAAI,KAAK,yBACP,OAAO,MAAM,KAAK,2BAA2B;EAG/C,MAAM,KAAK,mBAAmB;EAE9B,IAAI,eAAe,EAAE,UAAU,CAAC,EAAW;EAE3C,IAAI,MAAM,gBAAgB,KAAK,QAAQ,GACrC,IAAI;GACF,eAAgB,MAAM,iBAAiB,KAAK,QAAQ;EACtD,SAAS,OAAO;GACd,QAAQ,MAAM,2CAA2C,KAAK;GAC9D,eAAe,EAAE,UAAU,CAAC,EAAE;EAChC;OAEA,eAAe,EAAE,UAAU,CAAC,EAAE;EAGhC,aAAa,SAAS,KAAK,GAAG,KAAK,QAAQ;EAE3C,IAAI;GACF,MAAM,GAAG,SAAS,UAAU,KAAK,UAAU,kBAAkB,cAAc,CAAC,CAAC;GAE7E,KAAK,OAAO;EACd,SAAS,OAAO;GACd,QAAQ,MAAM,wBAAwB,KAAK;GAE3C,KAAK,YAAY;EACnB;CACF;;;;CAKA,MAAgB,6BAA4C;EAE1D,KAAK,uBAAuB;EAG5B,KAAK,MAAM,OAAO,KAAK,iBAAiB;GACtC,MAAM,gBAAgB,KAAK,KAAK,KAAK,aAAa,GAAG;GAErD,MAAM,qBAAqB,aAAa;GAExC,MAAM,WAAW,KAAK,KAAK,eAAe,GAAG,KAAK,SAAS,GAAG,KAAK,WAAW;GAE9E,MAAM,KAAK,mBAAmB,QAAQ;GAEtC,IAAI,eAAoC,EAAE,UAAU,CAAC,EAAE;GACvD,IAAI,MAAM,gBAAgB,QAAQ,GAChC,IAAI;IACF,eAAgB,MAAM,iBAAiB,QAAQ;GACjD,SAAS,OAAO;IACd,QAAQ,MAAM,2CAA2C,KAAK;IAC9D,eAAe,EAAE,UAAU,CAAC,EAAE;GAChC;QAEA,eAAe,EAAE,UAAU,CAAC,EAAE;GAGhC,aAAa,SAAS,KAAK,GAAG,KAAK,gBAAgB,IAAI;GAEvD,IAAI;IACF,MAAM,GAAG,SAAS,UAAU,UAAU,kBAAkB,cAAc,CAAC,CAAC;GAC1E,SAAS,OAAO;IACd,QAAQ,MAAM,wBAAwB,KAAK;IAC3C,KAAK,YAAY;GACnB;EACF;EAEA,KAAK,OAAO;CACd;AACF"}

package/esm/channels/sentry-log.d.mts

@@ -0,0 +1,182 @@
+import { BasicLogConfigurations, LogLevel, LoggingData } from "../types.mjs";
+import { LogChannel } from "../log-channel.mjs";
+
+//#region ../@warlock.js/logger/src/channels/sentry-log.d.ts
+/**
+ * Sentry severity levels — the `@sentry/node` `SeverityLevel` union.
+ */
+type SentrySeverityLevel = "fatal" | "error" | "warning" | "log" | "info" | "debug";
+/**
+ * The Sentry `Scope` surface used while building a single event.
+ */
+interface SentryScopeLike {
+  setLevel(level: SentrySeverityLevel): void;
+  setTags(tags: Record<string, string>): void;
+  setContext(name: string, context: Record<string, unknown> | null): void;
+}
+/**
+ * A Sentry breadcrumb, as passed to `addBreadcrumb`.
+ */
+type SentryBreadcrumb = {
+  category?: string;
+  message?: string;
+  level?: SentrySeverityLevel;
+  data?: Record<string, unknown>;
+};
+/**
+ * The subset of the `@sentry/node` API `SentryLog` calls. The `@sentry/node`
+ * namespace satisfies this shape, so an app can pass it straight through as
+ * `client`; a test (or a custom forwarder) can supply a compatible stand-in.
+ */
+interface SentryForwarder {
+  captureException(exception: unknown): string;
+  captureMessage(message: string, level?: SentrySeverityLevel): string;
+  addBreadcrumb(breadcrumb: SentryBreadcrumb): void;
+  withScope(callback: (scope: SentryScopeLike) => void): void;
+  flush(timeout?: number): Promise<boolean>;
+}
+/**
+ * Sentry initialization options. Mirrors the common `@sentry/node` `NodeOptions`
+ * fields; the index signature keeps any other SDK option valid without coupling
+ * to the SDK's types.
+ */
+type SentryInitOptions = {
+  dsn?: string;
+  environment?: string;
+  release?: string;
+  sampleRate?: number;
+  [key: string]: unknown;
+};
+type SentryLogConfig = BasicLogConfigurations & {
+  /**
+   * Reuse an already-initialized Sentry instance — typically the `@sentry/node`
+   * namespace from an app that already calls `Sentry.init(...)`. When set, the
+   * channel forwards through it and never imports or re-initializes the SDK.
+   */
+  client?: SentryForwarder;
+  /**
+   * Initialize Sentry from these options instead of reusing a host client. The
+   * channel lazily imports `@sentry/node` and calls `Sentry.init(options)` once,
+   * guarded so it never clobbers an existing client.
+   */
+  options?: SentryInitOptions;
+  /**
+   * Levels delivered as Sentry *events* (these consume the error quota). Every
+   * other level is recorded as a breadcrumb that rides along with the next
+   * event, costing no quota.
+   *
+   * @default ["fatal", "error", "warn"]
+   */
+  eventLevels?: LogLevel[];
+  /**
+   * Milliseconds `flush()` waits for the transport to drain on shutdown.
+   *
+   * @default 2000
+   */
+  flushTimeout?: number;
+};
+/**
+ * Forwards log entries to Sentry.
+ *
+ * Entries at an `eventLevels` level (`error` / `warn` by default) become Sentry
+ * **events**: an `Error` message via `captureException` (preserving the real
+ * stack), any other message via `captureMessage`. Every other level becomes a
+ * **breadcrumb** — buffered and attached to the next event, consuming no error
+ * quota. `module` / `action` are attached as searchable tags and the entry's
+ * `context` as a structured Sentry context.
+ *
+ * The SDK is an optional peer: pass an existing `client` (reused as-is) or
+ * `options` (the channel lazily imports `@sentry/node` and initializes it). On
+ * graceful shutdown, `await log.flush()` drains pending events via
+ * `Sentry.flush(timeout)`.
+ *
+ * @example
+ * // Existing app — reuse the initialized Sentry client
+ * import * as Sentry from "@sentry/node";
+ * log.addChannel(new SentryLog({ client: Sentry }));
+ *
+ * @example
+ * // New app — let the channel initialize Sentry
+ * log.addChannel(new SentryLog({ options: { dsn: process.env.SENTRY_DSN } }));
+ */
+declare class SentryLog extends LogChannel<SentryLogConfig> {
+  /**
+   * {@inheritdoc}
+   */
+  name: string;
+  /**
+   * {@inheritdoc}
+   */
+  description: string;
+  /**
+   * {@inheritdoc}
+   */
+  protected defaultConfigurations: SentryLogConfig;
+  /**
+   * The resolved forwarder — the injected `client` or the lazily-imported
+   * `@sentry/node` namespace. `undefined` until `init()` resolves, and when the
+   * SDK is absent (then `log()` surfaces the install message once).
+   */
+  private sentry?;
+  /**
+   * Guards the one-time "@sentry/node is not installed" notice so a missing SDK
+   * doesn't spam stderr on every entry.
+   */
+  private warnedMissing;
+  /**
+   * Resolve an injected `client` (the Sentry namespace) **synchronously**, so an
+   * entry logged on the same tick as construction — e.g. at app boot, before
+   * the base schedules `init()` on the next tick via `setTimeout(0)` — is not
+   * silently dropped. The `options` (lazy-import) path is inherently async and
+   * still resolves in `init()`.
+   */
+  constructor(configurations?: SentryLogConfig);
+  /**
+   * Resolve the forwarder: reuse the injected client, otherwise lazily import
+   * `@sentry/node` and (only when explicit `options` are supplied and no client
+   * exists yet) initialize it. Never throws — the base runs `init()` inside an
+   * un-awaited `setTimeout`, so a throw would become an unhandled rejection and
+   * `isInitialized` would never flip; a missing SDK is reported from `log()`.
+   */
+  protected init(): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  log(data: LoggingData): Promise<void>;
+  /**
+   * Drain pending Sentry events. Bounded by `flushTimeout` so an unreachable
+   * Sentry can never hang a graceful shutdown. No-op when the SDK is absent.
+   */
+  flush(): Promise<void>;
+  /**
+   * Whether the level should be sent as a Sentry event (vs a breadcrumb).
+   */
+  private isEventLevel;
+  /**
+   * Send an entry as a Sentry event. An `Error` message goes through
+   * `captureException` so Sentry parses the real stack and groups properly;
+   * any other message goes through `captureMessage`. `module` / `action` are
+   * attached as tags and `context` as a structured context, scoped to this
+   * event only via `withScope`.
+   */
+  private captureEvent;
+  /**
+   * Map a logger level to a Sentry severity. `success` has no Sentry
+   * equivalent, so it is reported as informational.
+   */
+  private toSentryLevel;
+  /**
+   * Coerce a message into the string Sentry's APIs expect — an `Error`'s
+   * `.message`, a string as-is, anything else safely JSON-serialized.
+   */
+  private toText;
+  /**
+   * Surface the install instructions exactly once when the SDK is absent. The
+   * logger can't log through itself here, so this writes to stderr — matching
+   * how the file channels report write failures.
+   */
+  private reportMissingSdk;
+}
+//#endregion
+export { SentryBreadcrumb, SentryForwarder, SentryInitOptions, SentryLog, SentryLogConfig, SentryScopeLike };
+//# sourceMappingURL=sentry-log.d.mts.map

package/esm/channels/sentry-log.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentry-log.d.mts","names":[],"sources":["../../../../../../../@warlock.js/logger/src/channels/sentry-log.ts"],"mappings":";;;;;;AAC8E;KAgBzE,mBAAA;;;AAAmB;UAWP,eAAA;EACf,QAAA,CAAS,KAAA,EAAO,mBAAA;EAChB,OAAA,CAAQ,IAAA,EAAM,MAAA;EACd,UAAA,CAAW,IAAA,UAAc,OAAA,EAAS,MAAA;AAAA;;;;KAMxB,gBAAA;EACV,QAAA;EACA,OAAA;EACA,KAAA,GAAQ,mBAAA;EACR,IAAA,GAAO,MAAM;AAAA;;;;;;UAQE,eAAA;EACf,gBAAA,CAAiB,SAAA;EACjB,cAAA,CAAe,OAAA,UAAiB,KAAA,GAAQ,mBAAA;EACxC,aAAA,CAAc,UAAA,EAAY,gBAAA;EAC1B,SAAA,CAAU,QAAA,GAAW,KAAA,EAAO,eAAA;EAC5B,KAAA,CAAM,OAAA,YAAmB,OAAA;AAAA;;;;;;KAQf,iBAAA;EACV,GAAA;EACA,WAAA;EACA,OAAA;EACA,UAAA;EAAA,CACC,GAAA;AAAA;AAAA,KAyDS,eAAA,GAAkB,sBAAA;EAtEI;;;;;EA4EhC,MAAA,GAAS,eAAA;EA/E+B;;;;;EAqFxC,OAAA,GAAU,iBAAA;EAnFkB;;;;;;;EA2F5B,WAAA,GAAc,QAAA;EAlFJ;;;;;EAwFV,YAAA;AAAA;;;;AAnFY;AAyDd;;;;;;;;;;;;;;;;;;AA0Bc;AA2Bd;cAAa,SAAA,SAAkB,UAAA,CAAW,eAAA;;;;EAIjC,IAAA;EAqDiB;;;EAhDjB,WAAA;EATsB;;;EAAA,UAenB,qBAAA,EAAuB,eAAA;EAfO;;;;;EAAA,QAyBhC,MAAA;EAMA;;;;EAAA,QAAA,aAAA;EA0BgB;;;;;;;cAjBL,cAAA,GAAiB,eAAA;EA4G5B;;;;;AAiEgB;;EAjEhB,UA3FQ,IAAA,IAAQ,OAAA;;;;EA2BX,GAAA,CAAI,IAAA,EAAM,WAAA,GAAc,OAAA;;;;;EA0CxB,KAAA,IAAS,OAAA;;;;UAWd,YAAA;;;;;;;;UAWA,YAAA;;;;;UAiCA,aAAA;;;;;UAeA,MAAA;;;;;;UAiBA,gBAAA;AAAA"}

package/esm/channels/sentry-log.mjs

@@ -0,0 +1,202 @@
+import { LogChannel } from "../log-channel.mjs";
+import { safeJsonStringify } from "../utils/safe-json-stringify.mjs";
+
+//#region ../@warlock.js/logger/src/channels/sentry-log.ts
+let Sentry;
+let isModuleExists = null;
+let loadingPromise;
+const SENTRY_INSTALL_INSTRUCTIONS = `
+The Sentry log channel requires the @sentry/node package.
+Install it with:
+
+  npm install @sentry/node
+
+Or with your preferred package manager:
+
+  pnpm add @sentry/node
+  yarn add @sentry/node
+`.trim();
+/**
+* Load @sentry/node once, lazily and concurrency-safely. A bare catch maps any
+* import failure to "not installed" — the curated install message surfaces at
+* `log()` time, never as a boot-time module-resolution crash.
+*/
+function loadSentry() {
+	if (isModuleExists !== null) return Promise.resolve();
+	if (loadingPromise) return loadingPromise;
+	loadingPromise = (async () => {
+		try {
+			Sentry = await import("@sentry/node");
+			isModuleExists = true;
+		} catch {
+			isModuleExists = false;
+		}
+	})();
+	return loadingPromise;
+}
+/**
+* Forwards log entries to Sentry.
+*
+* Entries at an `eventLevels` level (`error` / `warn` by default) become Sentry
+* **events**: an `Error` message via `captureException` (preserving the real
+* stack), any other message via `captureMessage`. Every other level becomes a
+* **breadcrumb** — buffered and attached to the next event, consuming no error
+* quota. `module` / `action` are attached as searchable tags and the entry's
+* `context` as a structured Sentry context.
+*
+* The SDK is an optional peer: pass an existing `client` (reused as-is) or
+* `options` (the channel lazily imports `@sentry/node` and initializes it). On
+* graceful shutdown, `await log.flush()` drains pending events via
+* `Sentry.flush(timeout)`.
+*
+* @example
+* // Existing app — reuse the initialized Sentry client
+* import * as Sentry from "@sentry/node";
+* log.addChannel(new SentryLog({ client: Sentry }));
+*
+* @example
+* // New app — let the channel initialize Sentry
+* log.addChannel(new SentryLog({ options: { dsn: process.env.SENTRY_DSN } }));
+*/
+var SentryLog = class extends LogChannel {
+	/**
+	* Resolve an injected `client` (the Sentry namespace) **synchronously**, so an
+	* entry logged on the same tick as construction — e.g. at app boot, before
+	* the base schedules `init()` on the next tick via `setTimeout(0)` — is not
+	* silently dropped. The `options` (lazy-import) path is inherently async and
+	* still resolves in `init()`.
+	*/
+	constructor(configurations) {
+		super(configurations);
+		this.name = "sentry";
+		this.description = "Forwards entries to Sentry as events (error/warn) or breadcrumbs (everything else)";
+		this.defaultConfigurations = {
+			eventLevels: [
+				"fatal",
+				"error",
+				"warn"
+			],
+			flushTimeout: 2e3
+		};
+		this.warnedMissing = false;
+		const injected = this.config("client");
+		if (injected) this.sentry = injected;
+	}
+	/**
+	* Resolve the forwarder: reuse the injected client, otherwise lazily import
+	* `@sentry/node` and (only when explicit `options` are supplied and no client
+	* exists yet) initialize it. Never throws — the base runs `init()` inside an
+	* un-awaited `setTimeout`, so a throw would become an unhandled rejection and
+	* `isInitialized` would never flip; a missing SDK is reported from `log()`.
+	*/
+	async init() {
+		const injected = this.config("client");
+		if (injected) {
+			this.sentry = injected;
+			return;
+		}
+		await loadSentry();
+		if (!Sentry) return;
+		const options = this.config("options");
+		if (options && !Sentry.getClient()) Sentry.init(options);
+		this.sentry = Sentry;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async log(data) {
+		if (!this.shouldBeLogged(data)) return;
+		if (isModuleExists === null) await loadSentry();
+		if (!this.sentry) {
+			this.reportMissingSdk();
+			return;
+		}
+		const { module, action, message, type: level, context } = data;
+		if (this.isEventLevel(level)) {
+			this.captureEvent(this.sentry, {
+				module,
+				action,
+				message,
+				level,
+				context
+			});
+			return;
+		}
+		this.sentry.addBreadcrumb({
+			category: module,
+			message: this.toText(message),
+			level: this.toSentryLevel(level),
+			data: context
+		});
+	}
+	/**
+	* Drain pending Sentry events. Bounded by `flushTimeout` so an unreachable
+	* Sentry can never hang a graceful shutdown. No-op when the SDK is absent.
+	*/
+	async flush() {
+		if (!this.sentry) return;
+		await this.sentry.flush(this.config("flushTimeout"));
+	}
+	/**
+	* Whether the level should be sent as a Sentry event (vs a breadcrumb).
+	*/
+	isEventLevel(level) {
+		return Boolean(this.config("eventLevels")?.includes(level));
+	}
+	/**
+	* Send an entry as a Sentry event. An `Error` message goes through
+	* `captureException` so Sentry parses the real stack and groups properly;
+	* any other message goes through `captureMessage`. `module` / `action` are
+	* attached as tags and `context` as a structured context, scoped to this
+	* event only via `withScope`.
+	*/
+	captureEvent(sentry, entry) {
+		const { module, action, message, level, context } = entry;
+		const sentryLevel = this.toSentryLevel(level);
+		sentry.withScope((scope) => {
+			scope.setLevel(sentryLevel);
+			scope.setTags({
+				module,
+				action
+			});
+			if (context) scope.setContext("context", context);
+			if (message instanceof Error) sentry.captureException(message);
+			else sentry.captureMessage(this.toText(message), sentryLevel);
+		});
+	}
+	/**
+	* Map a logger level to a Sentry severity. `success` has no Sentry
+	* equivalent, so it is reported as informational.
+	*/
+	toSentryLevel(level) {
+		switch (level) {
+			case "warn": return "warning";
+			case "success": return "info";
+			default: return level;
+		}
+	}
+	/**
+	* Coerce a message into the string Sentry's APIs expect — an `Error`'s
+	* `.message`, a string as-is, anything else safely JSON-serialized.
+	*/
+	toText(message) {
+		if (typeof message === "string") return message;
+		if (message instanceof Error) return message.message;
+		return safeJsonStringify(message);
+	}
+	/**
+	* Surface the install instructions exactly once when the SDK is absent. The
+	* logger can't log through itself here, so this writes to stderr — matching
+	* how the file channels report write failures.
+	*/
+	reportMissingSdk() {
+		if (isModuleExists === false && !this.warnedMissing) {
+			this.warnedMissing = true;
+			console.error(SENTRY_INSTALL_INSTRUCTIONS);
+		}
+	}
+};
+
+//#endregion
+export { SentryLog };
+//# sourceMappingURL=sentry-log.mjs.map

package/esm/channels/sentry-log.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentry-log.mjs","names":[],"sources":["../../../../../../../@warlock.js/logger/src/channels/sentry-log.ts"],"sourcesContent":["import { LogChannel } from \"../log-channel\";\r\nimport type { BasicLogConfigurations, LoggingData, LogLevel } from \"../types\";\r\nimport { safeJsonStringify } from \"../utils/safe-json-stringify\";\r\n\r\n// ── @sentry/node as an optional peer ─────────────────────────────────────────\r\n// @sentry/node is referenced ONLY through the local minimal types below — never\r\n// via `typeof import(\"@sentry/node\")`. This package is served as source\r\n// (`main` → `./src/index.ts`), so its `.ts` becomes part of a consumer's TS\r\n// program; a static type reference to the SDK would force module resolution and\r\n// break every consumer who (correctly) never installs the optional peer with a\r\n// TS2307 \"cannot find module\". The runtime import uses an indirect specifier for\r\n// the same reason, and its result is cast to these shapes. The shapes mirror the\r\n// stable `@sentry/node` public API (unchanged across v8–v10).\r\n\r\n/**\r\n * Sentry severity levels — the `@sentry/node` `SeverityLevel` union.\r\n */\r\ntype SentrySeverityLevel =\r\n  | \"fatal\"\r\n  | \"error\"\r\n  | \"warning\"\r\n  | \"log\"\r\n  | \"info\"\r\n  | \"debug\";\r\n\r\n/**\r\n * The Sentry `Scope` surface used while building a single event.\r\n */\r\nexport interface SentryScopeLike {\r\n  setLevel(level: SentrySeverityLevel): void;\r\n  setTags(tags: Record<string, string>): void;\r\n  setContext(name: string, context: Record<string, unknown> | null): void;\r\n}\r\n\r\n/**\r\n * A Sentry breadcrumb, as passed to `addBreadcrumb`.\r\n */\r\nexport type SentryBreadcrumb = {\r\n  category?: string;\r\n  message?: string;\r\n  level?: SentrySeverityLevel;\r\n  data?: Record<string, unknown>;\r\n};\r\n\r\n/**\r\n * The subset of the `@sentry/node` API `SentryLog` calls. The `@sentry/node`\r\n * namespace satisfies this shape, so an app can pass it straight through as\r\n * `client`; a test (or a custom forwarder) can supply a compatible stand-in.\r\n */\r\nexport interface SentryForwarder {\r\n  captureException(exception: unknown): string;\r\n  captureMessage(message: string, level?: SentrySeverityLevel): string;\r\n  addBreadcrumb(breadcrumb: SentryBreadcrumb): void;\r\n  withScope(callback: (scope: SentryScopeLike) => void): void;\r\n  flush(timeout?: number): Promise<boolean>;\r\n}\r\n\r\n/**\r\n * Sentry initialization options. Mirrors the common `@sentry/node` `NodeOptions`\r\n * fields; the index signature keeps any other SDK option valid without coupling\r\n * to the SDK's types.\r\n */\r\nexport type SentryInitOptions = {\r\n  dsn?: string;\r\n  environment?: string;\r\n  release?: string;\r\n  sampleRate?: number;\r\n  [key: string]: unknown;\r\n};\r\n\r\n/**\r\n * The lazily-imported `@sentry/node` namespace surface — the forwarder plus the\r\n * lifecycle calls the channel uses when it owns initialization.\r\n */\r\ninterface SentryNamespace extends SentryForwarder {\r\n  init(options?: SentryInitOptions): unknown;\r\n  getClient(): unknown;\r\n}\r\n\r\nlet Sentry: SentryNamespace | undefined;\r\nlet isModuleExists: boolean | null = null;\r\nlet loadingPromise: Promise<void> | undefined;\r\n\r\nconst SENTRY_INSTALL_INSTRUCTIONS = `\r\nThe Sentry log channel requires the @sentry/node package.\r\nInstall it with:\r\n\r\n  npm install @sentry/node\r\n\r\nOr with your preferred package manager:\r\n\r\n  pnpm add @sentry/node\r\n  yarn add @sentry/node\r\n`.trim();\r\n\r\n/**\r\n * Load @sentry/node once, lazily and concurrency-safely. A bare catch maps any\r\n * import failure to \"not installed\" — the curated install message surfaces at\r\n * `log()` time, never as a boot-time module-resolution crash.\r\n */\r\nfunction loadSentry(): Promise<void> {\r\n  if (isModuleExists !== null) {\r\n    return Promise.resolve();\r\n  }\r\n\r\n  if (loadingPromise) {\r\n    return loadingPromise;\r\n  }\r\n\r\n  loadingPromise = (async () => {\r\n    try {\r\n      // Indirect specifier (typed `string`, not a literal) so TypeScript never\r\n      // statically resolves the optional peer — see the file header.\r\n      const sentryModule: string = \"@sentry/node\";\r\n      Sentry = (await import(sentryModule)) as unknown as SentryNamespace;\r\n      isModuleExists = true;\r\n    } catch {\r\n      isModuleExists = false;\r\n    }\r\n  })();\r\n\r\n  return loadingPromise;\r\n}\r\n\r\nexport type SentryLogConfig = BasicLogConfigurations & {\r\n  /**\r\n   * Reuse an already-initialized Sentry instance — typically the `@sentry/node`\r\n   * namespace from an app that already calls `Sentry.init(...)`. When set, the\r\n   * channel forwards through it and never imports or re-initializes the SDK.\r\n   */\r\n  client?: SentryForwarder;\r\n  /**\r\n   * Initialize Sentry from these options instead of reusing a host client. The\r\n   * channel lazily imports `@sentry/node` and calls `Sentry.init(options)` once,\r\n   * guarded so it never clobbers an existing client.\r\n   */\r\n  options?: SentryInitOptions;\r\n  /**\r\n   * Levels delivered as Sentry *events* (these consume the error quota). Every\r\n   * other level is recorded as a breadcrumb that rides along with the next\r\n   * event, costing no quota.\r\n   *\r\n   * @default [\"fatal\", \"error\", \"warn\"]\r\n   */\r\n  eventLevels?: LogLevel[];\r\n  /**\r\n   * Milliseconds `flush()` waits for the transport to drain on shutdown.\r\n   *\r\n   * @default 2000\r\n   */\r\n  flushTimeout?: number;\r\n};\r\n\r\n/**\r\n * Forwards log entries to Sentry.\r\n *\r\n * Entries at an `eventLevels` level (`error` / `warn` by default) become Sentry\r\n * **events**: an `Error` message via `captureException` (preserving the real\r\n * stack), any other message via `captureMessage`. Every other level becomes a\r\n * **breadcrumb** — buffered and attached to the next event, consuming no error\r\n * quota. `module` / `action` are attached as searchable tags and the entry's\r\n * `context` as a structured Sentry context.\r\n *\r\n * The SDK is an optional peer: pass an existing `client` (reused as-is) or\r\n * `options` (the channel lazily imports `@sentry/node` and initializes it). On\r\n * graceful shutdown, `await log.flush()` drains pending events via\r\n * `Sentry.flush(timeout)`.\r\n *\r\n * @example\r\n * // Existing app — reuse the initialized Sentry client\r\n * import * as Sentry from \"@sentry/node\";\r\n * log.addChannel(new SentryLog({ client: Sentry }));\r\n *\r\n * @example\r\n * // New app — let the channel initialize Sentry\r\n * log.addChannel(new SentryLog({ options: { dsn: process.env.SENTRY_DSN } }));\r\n */\r\nexport class SentryLog extends LogChannel<SentryLogConfig> {\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public name = \"sentry\";\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public description =\r\n    \"Forwards entries to Sentry as events (error/warn) or breadcrumbs (everything else)\";\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  protected defaultConfigurations: SentryLogConfig = {\r\n    eventLevels: [\"fatal\", \"error\", \"warn\"],\r\n    flushTimeout: 2_000,\r\n  };\r\n\r\n  /**\r\n   * The resolved forwarder — the injected `client` or the lazily-imported\r\n   * `@sentry/node` namespace. `undefined` until `init()` resolves, and when the\r\n   * SDK is absent (then `log()` surfaces the install message once).\r\n   */\r\n  private sentry?: SentryForwarder;\r\n\r\n  /**\r\n   * Guards the one-time \"@sentry/node is not installed\" notice so a missing SDK\r\n   * doesn't spam stderr on every entry.\r\n   */\r\n  private warnedMissing = false;\r\n\r\n  /**\r\n   * Resolve an injected `client` (the Sentry namespace) **synchronously**, so an\r\n   * entry logged on the same tick as construction — e.g. at app boot, before\r\n   * the base schedules `init()` on the next tick via `setTimeout(0)` — is not\r\n   * silently dropped. The `options` (lazy-import) path is inherently async and\r\n   * still resolves in `init()`.\r\n   */\r\n  public constructor(configurations?: SentryLogConfig) {\r\n    super(configurations);\r\n\r\n    const injected = this.config(\"client\");\r\n\r\n    if (injected) {\r\n      this.sentry = injected;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Resolve the forwarder: reuse the injected client, otherwise lazily import\r\n   * `@sentry/node` and (only when explicit `options` are supplied and no client\r\n   * exists yet) initialize it. Never throws — the base runs `init()` inside an\r\n   * un-awaited `setTimeout`, so a throw would become an unhandled rejection and\r\n   * `isInitialized` would never flip; a missing SDK is reported from `log()`.\r\n   */\r\n  protected async init(): Promise<void> {\r\n    const injected = this.config(\"client\");\r\n\r\n    if (injected) {\r\n      this.sentry = injected;\r\n\r\n      return;\r\n    }\r\n\r\n    await loadSentry();\r\n\r\n    if (!Sentry) {\r\n      return;\r\n    }\r\n\r\n    const options = this.config(\"options\");\r\n\r\n    if (options && !Sentry.getClient()) {\r\n      Sentry.init(options);\r\n    }\r\n\r\n    this.sentry = Sentry;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async log(data: LoggingData): Promise<void> {\r\n    if (!this.shouldBeLogged(data)) {\r\n      return;\r\n    }\r\n\r\n    if (isModuleExists === null) {\r\n      // wait until module is fully loaded\r\n      await loadSentry();\r\n    }\r\n\r\n    if (!this.sentry) {\r\n      this.reportMissingSdk();\r\n\r\n      return;\r\n    }\r\n\r\n    const { module, action, message, type: level, context } = data;\r\n\r\n    if (this.isEventLevel(level)) {\r\n      this.captureEvent(this.sentry, {\r\n        module,\r\n        action,\r\n        message,\r\n        level,\r\n        context,\r\n      });\r\n\r\n      return;\r\n    }\r\n\r\n    this.sentry.addBreadcrumb({\r\n      category: module,\r\n      message: this.toText(message),\r\n      level: this.toSentryLevel(level),\r\n      data: context,\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Drain pending Sentry events. Bounded by `flushTimeout` so an unreachable\r\n   * Sentry can never hang a graceful shutdown. No-op when the SDK is absent.\r\n   */\r\n  public async flush(): Promise<void> {\r\n    if (!this.sentry) {\r\n      return;\r\n    }\r\n\r\n    await this.sentry.flush(this.config(\"flushTimeout\"));\r\n  }\r\n\r\n  /**\r\n   * Whether the level should be sent as a Sentry event (vs a breadcrumb).\r\n   */\r\n  private isEventLevel(level: LogLevel): boolean {\r\n    return Boolean(this.config(\"eventLevels\")?.includes(level));\r\n  }\r\n\r\n  /**\r\n   * Send an entry as a Sentry event. An `Error` message goes through\r\n   * `captureException` so Sentry parses the real stack and groups properly;\r\n   * any other message goes through `captureMessage`. `module` / `action` are\r\n   * attached as tags and `context` as a structured context, scoped to this\r\n   * event only via `withScope`.\r\n   */\r\n  private captureEvent(\r\n    sentry: SentryForwarder,\r\n    entry: {\r\n      module: string;\r\n      action: string;\r\n      message: unknown;\r\n      level: LogLevel;\r\n      context?: Record<string, any>;\r\n    },\r\n  ): void {\r\n    const { module, action, message, level, context } = entry;\r\n    const sentryLevel = this.toSentryLevel(level);\r\n\r\n    sentry.withScope((scope) => {\r\n      scope.setLevel(sentryLevel);\r\n      scope.setTags({ module, action });\r\n\r\n      if (context) {\r\n        scope.setContext(\"context\", context);\r\n      }\r\n\r\n      if (message instanceof Error) {\r\n        sentry.captureException(message);\r\n      } else {\r\n        sentry.captureMessage(this.toText(message), sentryLevel);\r\n      }\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Map a logger level to a Sentry severity. `success` has no Sentry\r\n   * equivalent, so it is reported as informational.\r\n   */\r\n  private toSentryLevel(level: LogLevel): SentrySeverityLevel {\r\n    switch (level) {\r\n      case \"warn\":\r\n        return \"warning\";\r\n      case \"success\":\r\n        return \"info\";\r\n      default:\r\n        return level; // debug | info | error | fatal map 1:1\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Coerce a message into the string Sentry's APIs expect — an `Error`'s\r\n   * `.message`, a string as-is, anything else safely JSON-serialized.\r\n   */\r\n  private toText(message: unknown): string {\r\n    if (typeof message === \"string\") {\r\n      return message;\r\n    }\r\n\r\n    if (message instanceof Error) {\r\n      return message.message;\r\n    }\r\n\r\n    return safeJsonStringify(message);\r\n  }\r\n\r\n  /**\r\n   * Surface the install instructions exactly once when the SDK is absent. The\r\n   * logger can't log through itself here, so this writes to stderr — matching\r\n   * how the file channels report write failures.\r\n   */\r\n  private reportMissingSdk(): void {\r\n    if (isModuleExists === false && !this.warnedMissing) {\r\n      this.warnedMissing = true;\r\n      console.error(SENTRY_INSTALL_INSTRUCTIONS);\r\n    }\r\n  }\r\n}\r\n"],"mappings":";;;;AA+EA,IAAI;AACJ,IAAI,iBAAiC;AACrC,IAAI;AAEJ,MAAM,8BAA8B;;;;;;;;;;EAUlC,KAAK;;;;;;AAOP,SAAS,aAA4B;CACnC,IAAI,mBAAmB,MACrB,OAAO,QAAQ,QAAQ;CAGzB,IAAI,gBACF,OAAO;CAGT,kBAAkB,YAAY;EAC5B,IAAI;GAIF,SAAU,MAAM,OAAO;GACvB,iBAAiB;EACnB,QAAQ;GACN,iBAAiB;EACnB;CACF,EAAC,CAAE;CAEH,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,IAAa,YAAb,cAA+B,WAA4B;;;;;;;;CAwCzD,AAAO,YAAY,gBAAkC;EACnD,MAAM,cAAc;cArCR;qBAMZ;+BAKiD;GACjD,aAAa;IAAC;IAAS;IAAS;GAAM;GACtC,cAAc;EAChB;uBAawB;EAYtB,MAAM,WAAW,KAAK,OAAO,QAAQ;EAErC,IAAI,UACF,KAAK,SAAS;CAElB;;;;;;;;CASA,MAAgB,OAAsB;EACpC,MAAM,WAAW,KAAK,OAAO,QAAQ;EAErC,IAAI,UAAU;GACZ,KAAK,SAAS;GAEd;EACF;EAEA,MAAM,WAAW;EAEjB,IAAI,CAAC,QACH;EAGF,MAAM,UAAU,KAAK,OAAO,SAAS;EAErC,IAAI,WAAW,CAAC,OAAO,UAAU,GAC/B,OAAO,KAAK,OAAO;EAGrB,KAAK,SAAS;CAChB;;;;CAKA,MAAa,IAAI,MAAkC;EACjD,IAAI,CAAC,KAAK,eAAe,IAAI,GAC3B;EAGF,IAAI,mBAAmB,MAErB,MAAM,WAAW;EAGnB,IAAI,CAAC,KAAK,QAAQ;GAChB,KAAK,iBAAiB;GAEtB;EACF;EAEA,MAAM,EAAE,QAAQ,QAAQ,SAAS,MAAM,OAAO,YAAY;EAE1D,IAAI,KAAK,aAAa,KAAK,GAAG;GAC5B,KAAK,aAAa,KAAK,QAAQ;IAC7B;IACA;IACA;IACA;IACA;GACF,CAAC;GAED;EACF;EAEA,KAAK,OAAO,cAAc;GACxB,UAAU;GACV,SAAS,KAAK,OAAO,OAAO;GAC5B,OAAO,KAAK,cAAc,KAAK;GAC/B,MAAM;EACR,CAAC;CACH;;;;;CAMA,MAAa,QAAuB;EAClC,IAAI,CAAC,KAAK,QACR;EAGF,MAAM,KAAK,OAAO,MAAM,KAAK,OAAO,cAAc,CAAC;CACrD;;;;CAKA,AAAQ,aAAa,OAA0B;EAC7C,OAAO,QAAQ,KAAK,OAAO,aAAa,CAAC,EAAE,SAAS,KAAK,CAAC;CAC5D;;;;;;;;CASA,AAAQ,aACN,QACA,OAOM;EACN,MAAM,EAAE,QAAQ,QAAQ,SAAS,OAAO,YAAY;EACpD,MAAM,cAAc,KAAK,cAAc,KAAK;EAE5C,OAAO,WAAW,UAAU;GAC1B,MAAM,SAAS,WAAW;GAC1B,MAAM,QAAQ;IAAE;IAAQ;GAAO,CAAC;GAEhC,IAAI,SACF,MAAM,WAAW,WAAW,OAAO;GAGrC,IAAI,mBAAmB,OACrB,OAAO,iBAAiB,OAAO;QAE/B,OAAO,eAAe,KAAK,OAAO,OAAO,GAAG,WAAW;EAE3D,CAAC;CACH;;;;;CAMA,AAAQ,cAAc,OAAsC;EAC1D,QAAQ,OAAR;GACE,KAAK,QACH,OAAO;GACT,KAAK,WACH,OAAO;GACT,SACE,OAAO;EACX;CACF;;;;;CAMA,AAAQ,OAAO,SAA0B;EACvC,IAAI,OAAO,YAAY,UACrB,OAAO;EAGT,IAAI,mBAAmB,OACrB,OAAO,QAAQ;EAGjB,OAAO,kBAAkB,OAAO;CAClC;;;;;;CAOA,AAAQ,mBAAyB;EAC/B,IAAI,mBAAmB,SAAS,CAAC,KAAK,eAAe;GACnD,KAAK,gBAAgB;GACrB,QAAQ,MAAM,2BAA2B;EAC3C;CACF;AACF"}

package/esm/index.d.mts

@@ -3,9 +3,10 @@ import { LogChannel } from "./log-channel.mjs";
 import { ConsoleLog, ConsoleLogConfig } from "./channels/console-log.mjs";
 import { FileLog, FileLogConfig } from "./channels/file-log.mjs";
 import { JSONFileLog } from "./channels/json-file-log.mjs";
+import { SentryBreadcrumb, SentryForwarder, SentryInitOptions, SentryLog, SentryLogConfig, SentryScopeLike } from "./channels/sentry-log.mjs";
 import { Logger, log } from "./logger.mjs";
 import { applyRedact, mergeRedact } from "./redact/redact.mjs";
 import { captureAnyUnhandledRejection } from "./utils/capture-unhandled-errors.mjs";
 import { clearMessage } from "./utils/clear-message.mjs";
 import { safeJsonStringify } from "./utils/safe-json-stringify.mjs";
-export { AutoFlushEvent, BasicLogConfigurations, ConsoleLog, ConsoleLogConfig, DebugMode, FileLog, FileLogConfig, JSONFileLog, LogChannel, LogContract, LogLevel, LogMessage, Logger, LoggingData, OmittedLoggingData, RedactCensor, RedactConfig, applyRedact, captureAnyUnhandledRejection, clearMessage, log, mergeRedact, safeJsonStringify };
+export { AutoFlushEvent, BasicLogConfigurations, ConsoleLog, ConsoleLogConfig, DebugMode, FileLog, FileLogConfig, JSONFileLog, LogChannel, LogContract, LogLevel, LogMessage, Logger, LoggingData, OmittedLoggingData, RedactCensor, RedactConfig, SentryBreadcrumb, SentryForwarder, SentryInitOptions, SentryLog, SentryLogConfig, SentryScopeLike, applyRedact, captureAnyUnhandledRejection, clearMessage, log, mergeRedact, safeJsonStringify };

package/esm/index.mjs

@@ -3,6 +3,7 @@ import { ConsoleLog } from "./channels/console-log.mjs";
 import { FileLog } from "./channels/file-log.mjs";
 import { safeJsonStringify } from "./utils/safe-json-stringify.mjs";
 import { JSONFileLog } from "./channels/json-file-log.mjs";
+import { SentryLog } from "./channels/sentry-log.mjs";
 import "./channels/index.mjs";
 import { applyRedact, mergeRedact } from "./redact/redact.mjs";
 import { clearMessage } from "./utils/clear-message.mjs";
@@ -10,4 +11,4 @@ import { Logger, log } from "./logger.mjs";
 import { captureAnyUnhandledRejection } from "./utils/capture-unhandled-errors.mjs";
 import "./utils/index.mjs";
 
-export { ConsoleLog, FileLog, JSONFileLog, LogChannel, Logger, applyRedact, captureAnyUnhandledRejection, clearMessage, log, mergeRedact, safeJsonStringify };
+export { ConsoleLog, FileLog, JSONFileLog, LogChannel, Logger, SentryLog, applyRedact, captureAnyUnhandledRejection, clearMessage, log, mergeRedact, safeJsonStringify };

package/esm/log-channel.d.mts

@@ -1,6 +1,6 @@
 import { BasicLogConfigurations, LogContract, LoggingData, RedactConfig } from "./types.mjs";
 
-//#region ../../@warlock.js/logger/src/log-channel.d.ts
+//#region ../@warlock.js/logger/src/log-channel.d.ts
 declare abstract class LogChannel<Options extends BasicLogConfigurations = BasicLogConfigurations> implements LogContract {
   /**
    * Channel name
@@ -54,6 +54,14 @@ declare abstract class LogChannel<Options extends BasicLogConfigurations = Basic
    * Synchronously flush messages
    */
   flushSync?(): void;
+  /**
+   * Asynchronously flush buffered messages.
+   *
+   * Optional — channels that write synchronously per entry (e.g. `ConsoleLog`)
+   * don't implement it. Buffering channels override this to drain their buffer
+   * over async I/O so callers can `await log.flush()` on graceful shutdown.
+   */
+  flush?(): void | Promise<void>;
   /**
    * Read the channel's redact config (if any). Used by `Logger` to apply
    * per-channel additive redaction on top of the logger-wide floor.