@warlock.js/logger 5.29.0 → 5.31.0

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

@@ -1,7 +1,7 @@
 import { BasicLogConfigurations, LoggingData } from "../types.mjs";
 import { LogChannel } from "../log-channel.mjs";
 
-//#region ../logger/src/channels/console-log.d.ts
+//#region ../../packages/logger/src/channels/console-log.d.ts
 type ConsoleLogConfig = BasicLogConfigurations & {
   /**
    * Render the log entry's `context` object on a second line after the main

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

@@ -1 +1 @@
-{"version":3,"file":"console-log.d.mts","names":[],"sources":["../../../../../../../logger/src/channels/console-log.ts"],"mappings":";;;;KAKY,gBAAA,GAAmB,sBAAsB;;AAArD;;;;;;;;EAUE,WAAA;EAiFW;;;;;;EA1EX,YAAA;AAAA;AAAA,cA0EW,UAAA,SAAmB,UAAA,CAAW,gBAAA;EAAA;;;EAIlC,IAAA;EAUU;;;EALV,QAAA;;;;EAKA,GAAA,CAAI,IAAA,EAAM,WAAA;AAAA"}
+{"version":3,"file":"console-log.d.mts","names":[],"sources":["../../../../../../../../packages/logger/src/channels/console-log.ts"],"mappings":";;;;KAKY,gBAAA,GAAmB,sBAAsB;;AAArD;;;;;;;;EAUE,WAAA;EA6EW;;;;;;EAtEX,YAAA;AAAA;AAAA,cAsEW,UAAA,SAAmB,UAAA,CAAW,gBAAA;EAAA;;;EAIlC,IAAA;EAUU;;;EALV,QAAA;;;;EAKA,GAAA,CAAI,IAAA,EAAM,WAAA;AAAA"}

package/esm/channels/console-log.mjs

@@ -2,7 +2,7 @@ import { LogChannel } from "../log-channel.mjs";
 import { colors } from "@mongez/copper";
 import { inspect } from "util";
 
-//#region ../logger/src/channels/console-log.ts
+//#region ../../packages/logger/src/channels/console-log.ts
 /**
 * The longest level name (`success`) sets the tag column width. Padding every
 * level name to this width keeps the timestamp / module / action columns

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

@@ -1 +1 @@
-{"version":3,"file":"console-log.mjs","names":[],"sources":["../../../../../../../logger/src/channels/console-log.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { inspect } from \"util\";\nimport { LogChannel } from \"../log-channel\";\nimport type { BasicLogConfigurations, LoggingData, LogLevel } from \"../types\";\n\nexport type ConsoleLogConfig = BasicLogConfigurations & {\n  /**\n   * Render the log entry's `context` object on a second line after the main\n   * message. When `false`, context is silently dropped (the historical\n   * behavior). When `true`, contexts are pretty-printed with `util.inspect`\n   * — colored, depth-limited, ideal for development. Persistent channels\n   * (`FileLog`, `JSONFileLog`) always retain context regardless of this flag.\n   *\n   * @default false\n   */\n  showContext?: boolean;\n  /**\n   * Depth passed to `util.inspect` when rendering context. Only applies when\n   * `showContext` is enabled.\n   *\n   * @default 4\n   */\n  contextDepth?: number;\n};\n\n/**\n * The longest level name (`success`) sets the tag column width. Padding every\n * level name to this width keeps the timestamp / module / action columns\n * aligned across lines. The level icons are bare (text-style, single-cell)\n * glyphs, so padding the name alone produces true columns.\n */\nconst LEVEL_NAME_WIDTH = 7;\n\n/**\n * Per-level console presentation: the colored, fixed-width `{icon} {name}` tag\n * and the function that colors the message body.\n */\ntype LevelStyle = {\n  tag: string;\n  message: (message: LoggingData[\"message\"]) => string;\n};\n\n/**\n * Build a single-color, fixed-width tag — `{icon} {name}` with the name padded\n * so every tag spans the same number of columns.\n */\nfunction buildTag(\n  icon: string,\n  name: string,\n  color: (text: string) => string,\n): string {\n  return color(`${icon} ${name.padEnd(LEVEL_NAME_WIDTH)}`);\n}\n\n/**\n * Console styling per log level. The `fatal` tag is a bright-red background\n * badge — the same column width as the others (`\" ☠ fatal \"` is 9 cells, like\n * `{icon} {name.padEnd(7)}`), but impossible to miss in a wall of red `error`\n * lines, where a plain red tag would blend in.\n */\nconst LEVEL_STYLES: Record<LogLevel, LevelStyle> = {\n  debug: {\n    tag: buildTag(\"⚙\", \"debug\", colors.magentaBright),\n    message: colors.magentaBright,\n  },\n  info: {\n    tag: buildTag(\"ℹ\", \"info\", colors.blueBright),\n    message: colors.blueBright,\n  },\n  warn: {\n    tag: buildTag(\"⚠\", \"warn\", colors.yellow),\n    message: colors.yellowBright,\n  },\n  error: {\n    tag: buildTag(\"✗\", \"error\", colors.red),\n    message: colors.redBright,\n  },\n  success: {\n    tag: buildTag(\"✓\", \"success\", colors.green),\n    message: colors.greenBright,\n  },\n  fatal: {\n    tag: colors.bgRedBright(colors.whiteBright(colors.bold(\" ☠ fatal \"))),\n    message: colors.redBright.bold,\n  },\n};\n\n/**\n * Fallback for an unrecognized level — a plain `[log]` tag padded to the same\n * width so the columns stay aligned.\n */\nconst DEFAULT_STYLE: LevelStyle = {\n  tag: \"[log]\".padEnd(LEVEL_NAME_WIDTH + 2),\n  message: message => message as string,\n};\n\nexport class ConsoleLog extends LogChannel<ConsoleLogConfig> {\n  /**\n   * {@inheritdoc}\n   */\n  public name = \"console\";\n\n  /**\n   * Determine if channel is logging in terminal\n   */\n  public terminal = true;\n\n  /**\n   * {@inheritdoc}\n   */\n  public log(data: LoggingData) {\n    const { module, action, message, type: level } = data;\n\n    if (!this.shouldBeLogged(data)) return;\n\n    // Console shows time-only (HH:mm:ss.SSS) — within a dev session the date\n    // rarely changes, so the full ISO date + `T`/`Z` are just noise. Persistent\n    // channels (FileLog / JSONFileLog) keep the full ISO timestamp.\n    const time = new Date().toISOString().slice(11, 23); // i.e. \"10:22:00.000\"\n\n    const style = LEVEL_STYLES[level] ?? DEFAULT_STYLE;\n\n    // The slate timestamp recedes so the colored level + message lead the eye;\n    // module (cyan) and action (magenta) stay colored for subsystem scanning.\n    // `slate` (256-color neutral gray) reads cleaner than bright-black `gray`,\n    // which sits too close to the background on most terminal themes.\n    console.log(\n      style.tag,\n      colors.slate(`(${time})`),\n      colors.cyan(`[${module}]`),\n      colors.magenta(`[${action}]`),\n      style.message(message),\n    );\n\n    if (typeof message === \"object\") {\n      console.log(message);\n    }\n\n    // Render context on a second line when explicitly enabled. We only\n    // attempt rendering if there's anything meaningful to show — empty\n    // objects clutter the terminal without adding signal.\n    if (this.config(\"showContext\") && data.context && Object.keys(data.context).length > 0) {\n      const depth = this.config(\"contextDepth\") ?? 4;\n      console.log(\n        colors.slate(\"  ↳\"),\n        inspect(data.context, { colors: true, depth, breakLength: 80 }),\n      );\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;AA+BA,MAAM,mBAAmB;;;;;AAezB,SAAS,SACP,MACA,MACA,OACQ;CACR,OAAO,MAAM,GAAG,KAAK,GAAG,KAAK,OAAO,gBAAgB,GAAG;AACzD;;;;;;;AAQA,MAAM,eAA6C;CACjD,OAAO;EACL,KAAK,SAAS,KAAK,SAAS,OAAO,aAAa;EAChD,SAAS,OAAO;CAClB;CACA,MAAM;EACJ,KAAK,SAAS,KAAK,QAAQ,OAAO,UAAU;EAC5C,SAAS,OAAO;CAClB;CACA,MAAM;EACJ,KAAK,SAAS,KAAK,QAAQ,OAAO,MAAM;EACxC,SAAS,OAAO;CAClB;CACA,OAAO;EACL,KAAK,SAAS,KAAK,SAAS,OAAO,GAAG;EACtC,SAAS,OAAO;CAClB;CACA,SAAS;EACP,KAAK,SAAS,KAAK,WAAW,OAAO,KAAK;EAC1C,SAAS,OAAO;CAClB;CACA,OAAO;EACL,KAAK,OAAO,YAAY,OAAO,YAAY,OAAO,KAAK,WAAW,CAAC,CAAC;EACpE,SAAS,OAAO,UAAU;CAC5B;AACF;;;;;AAMA,MAAM,gBAA4B;CAChC,KAAK,QAAQ,OAAO,CAAoB;CACxC,UAAS,YAAW;AACtB;AAEA,IAAa,aAAb,cAAgC,WAA6B;;;cAI7C;kBAKI;;;;;CAKlB,AAAO,IAAI,MAAmB;EAC5B,MAAM,EAAE,QAAQ,QAAQ,SAAS,MAAM,UAAU;EAEjD,IAAI,CAAC,KAAK,eAAe,IAAI,GAAG;EAKhC,MAAM,wBAAO,IAAI,KAAK,EAAC,CAAC,YAAY,CAAC,CAAC,MAAM,IAAI,EAAE;EAElD,MAAM,QAAQ,aAAa,UAAU;EAMrC,QAAQ,IACN,MAAM,KACN,OAAO,MAAM,IAAI,KAAK,EAAE,GACxB,OAAO,KAAK,IAAI,OAAO,EAAE,GACzB,OAAO,QAAQ,IAAI,OAAO,EAAE,GAC5B,MAAM,QAAQ,OAAO,CACvB;EAEA,IAAI,OAAO,YAAY,UACrB,QAAQ,IAAI,OAAO;EAMrB,IAAI,KAAK,OAAO,aAAa,KAAK,KAAK,WAAW,OAAO,KAAK,KAAK,OAAO,CAAC,CAAC,SAAS,GAAG;GACtF,MAAM,QAAQ,KAAK,OAAO,cAAc,KAAK;GAC7C,QAAQ,IACN,OAAO,MAAM,KAAK,GAClB,QAAQ,KAAK,SAAS;IAAE,QAAQ;IAAM;IAAO,aAAa;GAAG,CAAC,CAChE;EACF;CACF;AACF"}
+{"version":3,"file":"console-log.mjs","names":[],"sources":["../../../../../../../../packages/logger/src/channels/console-log.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { inspect } from \"util\";\nimport { LogChannel } from \"../log-channel\";\nimport type { BasicLogConfigurations, LoggingData, LogLevel } from \"../types\";\n\nexport type ConsoleLogConfig = BasicLogConfigurations & {\n  /**\n   * Render the log entry's `context` object on a second line after the main\n   * message. When `false`, context is silently dropped (the historical\n   * behavior). When `true`, contexts are pretty-printed with `util.inspect`\n   * — colored, depth-limited, ideal for development. Persistent channels\n   * (`FileLog`, `JSONFileLog`) always retain context regardless of this flag.\n   *\n   * @default false\n   */\n  showContext?: boolean;\n  /**\n   * Depth passed to `util.inspect` when rendering context. Only applies when\n   * `showContext` is enabled.\n   *\n   * @default 4\n   */\n  contextDepth?: number;\n};\n\n/**\n * The longest level name (`success`) sets the tag column width. Padding every\n * level name to this width keeps the timestamp / module / action columns\n * aligned across lines. The level icons are bare (text-style, single-cell)\n * glyphs, so padding the name alone produces true columns.\n */\nconst LEVEL_NAME_WIDTH = 7;\n\n/**\n * Per-level console presentation: the colored, fixed-width `{icon} {name}` tag\n * and the function that colors the message body.\n */\ntype LevelStyle = {\n  tag: string;\n  message: (message: LoggingData[\"message\"]) => string;\n};\n\n/**\n * Build a single-color, fixed-width tag — `{icon} {name}` with the name padded\n * so every tag spans the same number of columns.\n */\nfunction buildTag(icon: string, name: string, color: (text: string) => string): string {\n  return color(`${icon} ${name.padEnd(LEVEL_NAME_WIDTH)}`);\n}\n\n/**\n * Console styling per log level. The `fatal` tag is a bright-red background\n * badge — the same column width as the others (`\" ☠ fatal \"` is 9 cells, like\n * `{icon} {name.padEnd(7)}`), but impossible to miss in a wall of red `error`\n * lines, where a plain red tag would blend in.\n */\nconst LEVEL_STYLES: Record<LogLevel, LevelStyle> = {\n  debug: {\n    tag: buildTag(\"⚙\", \"debug\", colors.magentaBright),\n    message: colors.magentaBright,\n  },\n  info: {\n    tag: buildTag(\"ℹ\", \"info\", colors.blueBright),\n    message: colors.blueBright,\n  },\n  warn: {\n    tag: buildTag(\"⚠\", \"warn\", colors.yellow),\n    message: colors.yellowBright,\n  },\n  error: {\n    tag: buildTag(\"✗\", \"error\", colors.red),\n    message: colors.redBright,\n  },\n  success: {\n    tag: buildTag(\"✓\", \"success\", colors.green),\n    message: colors.greenBright,\n  },\n  fatal: {\n    tag: colors.bgRedBright(colors.whiteBright(colors.bold(\" ☠ fatal \"))),\n    message: colors.redBright.bold,\n  },\n};\n\n/**\n * Fallback for an unrecognized level — a plain `[log]` tag padded to the same\n * width so the columns stay aligned.\n */\nconst DEFAULT_STYLE: LevelStyle = {\n  tag: \"[log]\".padEnd(LEVEL_NAME_WIDTH + 2),\n  message: (message) => message as string,\n};\n\nexport class ConsoleLog extends LogChannel<ConsoleLogConfig> {\n  /**\n   * {@inheritdoc}\n   */\n  public name = \"console\";\n\n  /**\n   * Determine if channel is logging in terminal\n   */\n  public terminal = true;\n\n  /**\n   * {@inheritdoc}\n   */\n  public log(data: LoggingData) {\n    const { module, action, message, type: level } = data;\n\n    if (!this.shouldBeLogged(data)) return;\n\n    // Console shows time-only (HH:mm:ss.SSS) — within a dev session the date\n    // rarely changes, so the full ISO date + `T`/`Z` are just noise. Persistent\n    // channels (FileLog / JSONFileLog) keep the full ISO timestamp.\n    const time = new Date().toISOString().slice(11, 23); // i.e. \"10:22:00.000\"\n\n    const style = LEVEL_STYLES[level] ?? DEFAULT_STYLE;\n\n    // The slate timestamp recedes so the colored level + message lead the eye;\n    // module (cyan) and action (magenta) stay colored for subsystem scanning.\n    // `slate` (256-color neutral gray) reads cleaner than bright-black `gray`,\n    // which sits too close to the background on most terminal themes.\n    console.log(\n      style.tag,\n      colors.slate(`(${time})`),\n      colors.cyan(`[${module}]`),\n      colors.magenta(`[${action}]`),\n      style.message(message),\n    );\n\n    if (typeof message === \"object\") {\n      console.log(message);\n    }\n\n    // Render context on a second line when explicitly enabled. We only\n    // attempt rendering if there's anything meaningful to show — empty\n    // objects clutter the terminal without adding signal.\n    if (this.config(\"showContext\") && data.context && Object.keys(data.context).length > 0) {\n      const depth = this.config(\"contextDepth\") ?? 4;\n      console.log(\n        colors.slate(\"  ↳\"),\n        inspect(data.context, { colors: true, depth, breakLength: 80 }),\n      );\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;AA+BA,MAAM,mBAAmB;;;;;AAezB,SAAS,SAAS,MAAc,MAAc,OAAyC;CACrF,OAAO,MAAM,GAAG,KAAK,GAAG,KAAK,OAAO,gBAAgB,GAAG;AACzD;;;;;;;AAQA,MAAM,eAA6C;CACjD,OAAO;EACL,KAAK,SAAS,KAAK,SAAS,OAAO,aAAa;EAChD,SAAS,OAAO;CAClB;CACA,MAAM;EACJ,KAAK,SAAS,KAAK,QAAQ,OAAO,UAAU;EAC5C,SAAS,OAAO;CAClB;CACA,MAAM;EACJ,KAAK,SAAS,KAAK,QAAQ,OAAO,MAAM;EACxC,SAAS,OAAO;CAClB;CACA,OAAO;EACL,KAAK,SAAS,KAAK,SAAS,OAAO,GAAG;EACtC,SAAS,OAAO;CAClB;CACA,SAAS;EACP,KAAK,SAAS,KAAK,WAAW,OAAO,KAAK;EAC1C,SAAS,OAAO;CAClB;CACA,OAAO;EACL,KAAK,OAAO,YAAY,OAAO,YAAY,OAAO,KAAK,WAAW,CAAC,CAAC;EACpE,SAAS,OAAO,UAAU;CAC5B;AACF;;;;;AAMA,MAAM,gBAA4B;CAChC,KAAK,QAAQ,OAAO,CAAoB;CACxC,UAAU,YAAY;AACxB;AAEA,IAAa,aAAb,cAAgC,WAA6B;;;cAI7C;kBAKI;;;;;CAKlB,AAAO,IAAI,MAAmB;EAC5B,MAAM,EAAE,QAAQ,QAAQ,SAAS,MAAM,UAAU;EAEjD,IAAI,CAAC,KAAK,eAAe,IAAI,GAAG;EAKhC,MAAM,wBAAO,IAAI,KAAK,EAAC,CAAC,YAAY,CAAC,CAAC,MAAM,IAAI,EAAE;EAElD,MAAM,QAAQ,aAAa,UAAU;EAMrC,QAAQ,IACN,MAAM,KACN,OAAO,MAAM,IAAI,KAAK,EAAE,GACxB,OAAO,KAAK,IAAI,OAAO,EAAE,GACzB,OAAO,QAAQ,IAAI,OAAO,EAAE,GAC5B,MAAM,QAAQ,OAAO,CACvB;EAEA,IAAI,OAAO,YAAY,UACrB,QAAQ,IAAI,OAAO;EAMrB,IAAI,KAAK,OAAO,aAAa,KAAK,KAAK,WAAW,OAAO,KAAK,KAAK,OAAO,CAAC,CAAC,SAAS,GAAG;GACtF,MAAM,QAAQ,KAAK,OAAO,cAAc,KAAK;GAC7C,QAAQ,IACN,OAAO,MAAM,KAAK,GAClB,QAAQ,KAAK,SAAS;IAAE,QAAQ;IAAM;IAAO,aAAa;GAAG,CAAC,CAChE;EACF;CACF;AACF"}

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

@@ -1,18 +1,61 @@
 import { BasicLogConfigurations, LogContract, LogLevel, LogMessage, LoggingData } from "../types.mjs";
 import { LogChannel } from "../log-channel.mjs";
+import { FileNameOption } from "./file-name-pattern.mjs";
 
-//#region ../logger/src/channels/file-log.d.ts
+//#region ../../packages/logger/src/channels/file-log.d.ts
+/** Default file name of a `daily` chunk: sortable ISO date. */
+declare const DAILY_FILE_NAME = "{YYYY}-{MM}-{DD}";
+/** Default file name of an `hourly` chunk: sortable ISO date and hour. */
+declare const HOURLY_FILE_NAME = "{YYYY}-{MM}-{DD}-{HH}";
+/** Default date part of a size-rotated file's name. */
+declare const ROTATE_FILE_NAME = "{YYYY}-{MM}-{DD}";
+/**
+ * Which old log files `FileLog` removes, on boot and whenever it starts a new
+ * file (a size rotation or a dated name rolling over). Only files in the log
+ * directory (each group directory with `groupBy`) whose names match the
+ * channel's file name pattern are considered; the file being written is
+ * always kept.
+ */
+type FileLogRetention = {
+  /**
+   * Keep at most this many matching files per directory, newest (by
+   * modification time) first, counting the file being written.
+   */
+  maxFiles?: number;
+  /**
+   * Remove matching files last modified more than this many days ago.
+   */
+  maxAgeDays?: number;
+  /**
+   * Which file names (with extension) belong to this channel. Defaults to one
+   * derived from `fileName` and `rotateFileName`; required when `fileName` is
+   * a function.
+   */
+  match?: RegExp;
+};
 type FileLogConfig = BasicLogConfigurations & {
   storagePath?: string;
   /**
-   * File name, without extension
+   * Base name, without extension: the file name of a `single` chunk and the
+   * `{name}` token of a `fileName` pattern.
+   *
+   * @default app
    */
   name?: string;
   /**
-   * chunk mode
-   * If set to `single`, the logs will be created in a single file, unless the rotate is set to true
-   * If set to `daily`, the logs will be created in a daily file, unless the rotate is set to true
-   * If set to `hourly`, the logs will be created in an hourly file, unless the rotate is set to true
+   * The file name, without extension: a pattern such as
+   * `"app-{YYYY}-{MM}-{DD}"` (tokens `{YYYY}` `{MM}` `{DD}` `{HH}` `{mm}`
+   * `{name}`, local time) or a function of the current date. Evaluated at
+   * every write, so a dated name starts a new file when it changes.
+   *
+   * @default by chunk: `single` → name, `daily` → `{YYYY}-{MM}-{DD}`, `hourly` → `{YYYY}-{MM}-{DD}-{HH}`
+   */
+  fileName?: FileNameOption;
+  /**
+   * chunk mode: picks the default `fileName`.
+   * `single` writes one file named `name`, `daily` one file per day
+   * (`YYYY-MM-DD`), `hourly` one per hour (`YYYY-MM-DD-HH`). Size rotation
+   * applies to each.
    * @default single
    */
   chunk?: "single" | "daily" | "hourly";
@@ -29,17 +72,26 @@ type FileLogConfig = BasicLogConfigurations & {
    */
   extension?: string;
   /**
-   * If rotate is set, the rotate name will be added to the file name suffixed with `-`
+   * Middle part of a size-rotated file's name:
+   * `<file name>-<rotateFileName>-<epoch ms>.<extension>`. Same forms as
+   * `fileName` (a token pattern or a function of the rotation date); text
+   * without tokens is used as is.
    *
-   * @default DD-MM-YYYY
+   * @default {YYYY}-{MM}-{DD}
    */
-  rotateFileName?: string;
+  rotateFileName?: FileNameOption;
   /**
    * Max file size before rotating the file
    *
    * @default 10MB
    */
   maxFileSize?: number;
+  /**
+   * Remove old log files on boot and whenever a new file is started.
+   *
+   * @default none (nothing is removed)
+   */
+  retention?: FileLogRetention;
   /**
    * Set the max messages that needs to be added before writing to the file
    *
@@ -99,14 +151,36 @@ declare class FileLog extends LogChannel<FileLogConfig> implements LogContract {
    * would otherwise leak one timer per channel.
    */
   protected flushIntervalHandle?: NodeJS.Timeout;
+  /**
+   * Set when a size rotation started a new file, so the next write prunes.
+   */
+  protected retentionDue: boolean;
+  /**
+   * File name of the last write, to notice a dated name rolling over.
+   */
+  protected lastFileName?: string;
+  /**
+   * The running (or last) prune, so prunes never overlap.
+   */
+  protected pruning?: Promise<void>;
+  /**
+   * Whether the "function `fileName` needs `retention.match`" error was
+   * already reported.
+   */
+  protected missingMatchReported: boolean;
+  /**
+   * {@inheritdoc}
+   */
+  protected setConfigurations(configurations: FileLogConfig): this;
   /**
    * Check file size for file rotation
    */
   protected checkAndRotateFile(filePath?: string): Promise<void>;
   /**
-   * Rotate log file
+   * Rotate the given log file (the active one by default) aside as
+   * `<file name>-<rotateFileName>-<epoch ms>.<extension>` in its directory.
    */
-  protected rotateLogFile(): Promise<void>;
+  protected rotateLogFile(filePath?: string): Promise<void>;
   /**
    * Flush messages
    *
@@ -133,7 +207,16 @@ declare class FileLog extends LogChannel<FileLogConfig> implements LogContract {
    */
   protected get maxMessagesToWrite(): number;
   /**
-   * Get file name
+   * The configured `name` option.
+   */
+  protected get baseName(): string;
+  /**
+   * The `fileName` option, or the chunk's default. `undefined` means the
+   * plain `name` of a `single` chunk, used as is (braces included).
+   */
+  protected get fileNamePattern(): FileNameOption | undefined;
+  /**
+   * Current file name, without extension
    */
   get fileName(): string;
   /**
@@ -152,6 +235,39 @@ declare class FileLog extends LogChannel<FileLogConfig> implements LogContract {
    * {@inheritdoc}
    */
   protected init(): Promise<void>;
+  /**
+   * Remove old log files as configured by `retention`. Runs on boot and
+   * whenever a new file is started; call it yourself to prune on demand.
+   * Never rejects: failures go to the channel error handler.
+   */
+  prune(): Promise<void>;
+  /**
+   * Prune once a write started a new file: after a size rotation, or when a
+   * dated file name rolled over. Never throws.
+   */
+  protected afterWrite(): Promise<void>;
+  /**
+   * Apply `retention` to every directory this channel writes to.
+   */
+  protected pruneFiles(): Promise<void>;
+  /**
+   * The expression a file name must match to be pruned, or `undefined` when
+   * none can be derived (a function `fileName` without `retention.match`).
+   */
+  protected retentionMatcher(retention: FileLogRetention): RegExp | undefined;
+  /**
+   * The log directory, or each group directory when `groupBy` is set.
+   */
+  protected retentionDirectories(): Promise<string[]>;
+  /**
+   * Remove the matching files of one directory that `retention` no longer
+   * keeps. Each failure is reported and the rest still run.
+   */
+  protected pruneDirectory(directory: string, matcher: RegExp, retention: FileLogRetention, activeFile: string): Promise<void>;
+  /**
+   * Send a retention failure to the channel error handler.
+   */
+  protected reportRetentionError(error: unknown, target: string): void;
   /**
    * Synchronously flush messages
    */
@@ -200,5 +316,5 @@ declare class FileLog extends LogChannel<FileLogConfig> implements LogContract {
   protected write(filePath: string, content: string): Promise<unknown>;
 }
 //#endregion
-export { FileLog, FileLogConfig };
+export { DAILY_FILE_NAME, FileLog, FileLogConfig, FileLogRetention, HOURLY_FILE_NAME, ROTATE_FILE_NAME };
 //# sourceMappingURL=file-log.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"file-log.d.mts","names":[],"sources":["../../../../../../../logger/src/channels/file-log.ts"],"mappings":";;;;KAgBY,aAAA,GAAgB,sBAAA;EAC1B,WAAA;EADU;;;EAKV,IAAA;EAL0B;;;;;;;EAa1B,KAAA;EA8BA;;;;;EAxBA,MAAA;EA4CE;;AAAI;AAIR;;EA1CE,SAAA;EA0CsC;;;;;EApCtC,cAAA;EA6F2D;;;;;EAvF3D,WAAA;EA2T8C;;;;;EArT9C,kBAAA;EAwB2E;;;;;;;EAhB3E,OAAA;EA8BU;;;;;EAxBV,MAAA,GAAS,QAAQ;EAuDP;;;EAnDV,UAAA;IACE,IAAA;IACA,IAAA;EAAA;AAAA;AAAA,cAIS,OAAA,SAAgB,UAAA,CAAW,aAAA,aAA0B,WAAA;EAiGtD;;;EA7FH,IAAA;EA6II;;;EAAA,UAxID,QAAA,EAAU,UAAA;EA8KJ;;;EAAA,UAzKN,eAAA,EAAiB,MAAA,SAAe,UAAA;EAqNpB;;;EAAA,UAhNZ,qBAAA,EAAuB,aAAA;EAiOC;;;EAAA,UA5MxB,aAAA;EAwQI;;;EAAA,UAnQJ,SAAA;EAkSoC;;;;;EAAA,UA3RpC,mBAAA,GAAsB,MAAA,CAAO,OAAA;EAuUgB;AAAA;;EAAA,UAlUvC,kBAAA,CAAmB,QAAA,YAAwB,OAAA;;;;YAoB3C,aAAA,IAAa,OAAA;;;;;;;;;YAoBnB,gBAAA;;;;;;;;EAkBH,OAAA;;;;MAYI,QAAA;;;;gBAWG,kBAAA;;;;MAOH,QAAA;;;;MAiBA,SAAA;;;;gBAOG,OAAA;;;;MAOH,WAAA;;;;YAOK,IAAA,IAAI,OAAA;;;;EAWb,SAAA;;;;;;;;;;EAiCM,KAAA,IAAS,OAAA;;;;EAiBT,GAAA,CAAI,IAAA,EAAM,WAAA,GAAW,OAAA;;;;YAyClB,8BAAA,IAA8B,OAAA;;;;YASpC,MAAA;;;;gBAUI,uBAAA;;;;YAOE,mBAAA,IAAmB,OAAA;;;;YAwBnB,0BAAA,IAA8B,OAAA;;;;YA8BpC,sBAAA;;;;YAcM,KAAA,CAAM,QAAA,UAAkB,OAAA,WAAe,OAAA;AAAA"}
+{"version":3,"file":"file-log.d.mts","names":[],"sources":["../../../../../../../../packages/logger/src/channels/file-log.ts"],"mappings":";;;;;;cAuBa,eAAA;;cAGA,gBAAA;;cAGA,gBAAA;AAHb;;;;AAA6B;AAG7B;;AAHA,KAcY,gBAAA;EAXiB;AAAA;AAW7B;;EAKE,QAAA;EAUc;;;EANd,UAAA;EAMQ;;AAAM;AAGhB;;EAHE,KAAA,GAAQ,MAAM;AAAA;AAAA,KAGJ,aAAA,GAAgB,sBAAA;EAC1B,WAAA;EAyDY;;;;;;EAlDZ,IAAA;EASA;;;;;;;;EAAA,QAAA,GAAW,cAAA;EAyCC;;;;;;;EAjCZ,KAAA;EA2DM;AAAA;AAIR;;;EAzDE,MAAA;EAkEoB;;;;;EA5DpB,SAAA;EA+H4C;;;;;;;;EAtH5C,cAAA,GAAiB,cAAA;EA4WwC;;;;;EAtWzD,WAAA;EAqiBuB;;;;;EA/hBvB,SAAA,GAAY,gBAAA;EA8Be;;;;;EAxB3B,kBAAA;EAwBgE;;;;;;;EAhBhE,OAAA;EAmCiC;;;;;EA7BjC,MAAA,GAAS,QAAA;EAiEC;;;EA7DV,UAAA;IACE,IAAA;IACA,IAAA;EAAA;AAAA;AAAA,cAIS,OAAA,SAAgB,UAAA,CAAW,aAAA,aAA0B,WAAA;EAqF7B;;;EAjF5B,IAAA;EAsG+C;;;EAAA,UAjG5C,QAAA,EAAU,UAAA;EA2KN;;;EAAA,UAtKJ,eAAA,EAAiB,MAAA,SAAe,UAAA;EAwM/B;;;EAAA,UAnMD,qBAAA,EAAuB,aAAA;EAmOjB;;;EAAA,UAhNN,aAAA;EA2OM;;;EAAA,UAtON,SAAA;EAuRA;;;;;EAAA,UAhRA,mBAAA,GAAsB,MAAA,CAAO,OAAA;EAmVvB;;;EAAA,UA9UN,YAAA;EAiVG;;;EAAA,UA5UH,YAAA;EAuYA;;;EAAA,UAlYA,OAAA,GAAU,OAAA;EA+aP;;;;EAAA,UAzaH,oBAAA;EA0bwB;;;EAAA,UArbxB,iBAAA,CAAkB,cAAA,EAAgB,aAAA;EAif9B;;;EAAA,UAxeE,kBAAA,CAAmB,QAAA,YAAwB,OAAA;EA2gBb;;;;EAAA,UAtf9B,aAAA,CAAc,QAAA,YAAwB,OAAA;EAoiBC;;AAAA;;;;;;EAAA,UAngB7C,gBAAA;;;;;;;;EAkBH,OAAA;;;;MAYI,QAAA;;;;gBAWG,kBAAA;;;;gBAOA,QAAA;;;;;gBAQA,eAAA,IAAmB,cAAA;;;;MAmBtB,QAAA;;;;MAWA,SAAA;;;;gBAOG,OAAA;;;;MAOH,WAAA;;;;YAOK,IAAA,IAAI,OAAA;;;;;;EAeb,KAAA,IAAS,OAAA;;;;;YAYA,UAAA,IAAc,OAAA;;;;YAuBd,UAAA,IAAc,OAAA;;;;;YA0BpB,gBAAA,CAAiB,SAAA,EAAW,gBAAA,GAAmB,MAAA;;;;YAqCzC,oBAAA,IAAwB,OAAA;;;;;YA8BxB,cAAA,CACd,SAAA,UACA,OAAA,EAAS,MAAA,EACT,SAAA,EAAW,gBAAA,EACX,UAAA,WACC,OAAA;;;;YAyDO,oBAAA,CAAqB,KAAA,WAAgB,MAAA;;;;EAYxC,SAAA;;;;;;;;;;EAiCM,KAAA,IAAS,OAAA;;;;EAiBT,GAAA,CAAI,IAAA,EAAM,WAAA,GAAW,OAAA;;;;YAyClB,8BAAA,IAA8B,OAAA;;;;YASpC,MAAA;;;;gBAUI,uBAAA;;;;YAOE,mBAAA,IAAmB,OAAA;;;;YA4BnB,0BAAA,IAA8B,OAAA;;;;YAgCpC,sBAAA;;;;YAcM,KAAA,CAAM,QAAA,UAAkB,OAAA,WAAe,OAAA;AAAA"}

package/esm/channels/file-log.mjs

@@ -1,11 +1,19 @@
 import { LogChannel } from "../log-channel.mjs";
+import { escapeRegExp, fileNamePatternSource, renderFileName } from "./file-name-pattern.mjs";
 import { ensureDirectoryAsync } from "@warlock.js/fs";
 import dayjs from "dayjs";
 import fs from "fs";
 import { EOL } from "os";
 import path from "path";
 
-//#region ../logger/src/channels/file-log.ts
+//#region ../../packages/logger/src/channels/file-log.ts
+/** Default file name of a `daily` chunk: sortable ISO date. */
+const DAILY_FILE_NAME = "{YYYY}-{MM}-{DD}";
+/** Default file name of an `hourly` chunk: sortable ISO date and hour. */
+const HOURLY_FILE_NAME = "{YYYY}-{MM}-{DD}-{HH}";
+/** Default date part of a size-rotated file's name. */
+const ROTATE_FILE_NAME = "{YYYY}-{MM}-{DD}";
+const DAY_MS = 1440 * 60 * 1e3;
 var FileLog = class extends LogChannel {
 	constructor(..._args) {
 		super(..._args);
@@ -21,9 +29,7 @@ var FileLog = class extends LogChannel {
 			maxMessagesToWrite: 100,
 			filter: () => true,
 			maxFileSize: 10 * 1024 * 1024,
-			get rotateFileName() {
-				return dayjs().format("DD-MM-YYYY");
-			},
+			rotateFileName: ROTATE_FILE_NAME,
 			dateFormat: {
 				date: "DD-MM-YYYY",
 				time: "HH:mm:ss"
@@ -31,6 +37,15 @@ var FileLog = class extends LogChannel {
 		};
 		this.lastWriteTime = Date.now();
 		this.isWriting = false;
+		this.retentionDue = false;
+		this.missingMatchReported = false;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	setConfigurations(configurations) {
+		assertRetention(configurations.retention);
+		return super.setConfigurations(configurations);
 	}
 	/**
 	* Check file size for file rotation
@@ -38,19 +53,24 @@ var FileLog = class extends LogChannel {
 	async checkAndRotateFile(filePath = this.filePath) {
 		if (!this.config("rotate")) return;
 		try {
-			if ((await fs.promises.stat(filePath)).size >= this.config("maxFileSize")) await this.rotateLogFile();
+			if ((await fs.promises.stat(filePath)).size >= this.config("maxFileSize")) await this.rotateLogFile(filePath);
 		} catch (error) {
 			if (error.code !== "ENOENT") console.error("Error checking log file:", error);
 		}
 	}
 	/**
-	* Rotate log file
+	* Rotate the given log file (the active one by default) aside as
+	* `<file name>-<rotateFileName>-<epoch ms>.<extension>` in its directory.
 	*/
-	async rotateLogFile() {
-		const fileName = `${this.fileName}-${this.config("rotateFileName")}-${Date.now()}`;
+	async rotateLogFile(filePath = this.filePath) {
+		const now = /* @__PURE__ */ new Date();
 		const extension = this.extension;
-		const rotatedFilePath = path.join(this.storagePath, `${fileName}.${extension}`);
-		await fs.promises.rename(this.filePath, rotatedFilePath).catch((error) => {
+		const baseName = path.basename(filePath, `.${extension}`);
+		const rotateName = renderFileName(this.config("rotateFileName") ?? "{YYYY}-{MM}-{DD}", now, this.baseName);
+		const rotatedFilePath = path.join(path.dirname(filePath), `${baseName}-${rotateName}-${now.getTime()}.${extension}`);
+		await fs.promises.rename(filePath, rotatedFilePath).then(() => {
+			this.retentionDue = true;
+		}, (error) => {
 			console.error("Error rotating file:", error);
 		});
 	}
@@ -96,17 +116,32 @@ var FileLog = class extends LogChannel {
 		return this.config("maxMessagesToWrite");
 	}
 	/**
-	* Get file name
+	* The configured `name` option.
 	*/
-	get fileName() {
+	get baseName() {
+		return this.config("name") ?? "app";
+	}
+	/**
+	* The `fileName` option, or the chunk's default. `undefined` means the
+	* plain `name` of a `single` chunk, used as is (braces included).
+	*/
+	get fileNamePattern() {
+		const configured = this.config("fileName");
+		if (configured !== void 0) return configured;
 		switch (this.config("chunk")) {
-			case "single":
-			default: return this.config("name");
-			case "daily": return dayjs().format("DD-MM-YYYY");
-			case "hourly": return dayjs().format("DD-MM-YYYY-HH-00-00-a");
+			case "daily": return DAILY_FILE_NAME;
+			case "hourly": return HOURLY_FILE_NAME;
+			default: return;
 		}
 	}
 	/**
+	* Current file name, without extension
+	*/
+	get fileName() {
+		const pattern = this.fileNamePattern;
+		return pattern === void 0 ? this.baseName : renderFileName(pattern, /* @__PURE__ */ new Date(), this.baseName);
+	}
+	/**
 	* Get file extension
 	*/
 	get extension() {
@@ -131,6 +166,138 @@ var FileLog = class extends LogChannel {
 		const logsDirectory = this.storagePath;
 		await ensureDirectoryAsync(logsDirectory);
 		this.initMessageFlush();
+		await this.prune();
+	}
+	/**
+	* Remove old log files as configured by `retention`. Runs on boot and
+	* whenever a new file is started; call it yourself to prune on demand.
+	* Never rejects: failures go to the channel error handler.
+	*/
+	prune() {
+		const run = (this.pruning ?? Promise.resolve()).then(() => this.pruneFiles());
+		this.pruning = run;
+		return run;
+	}
+	/**
+	* Prune once a write started a new file: after a size rotation, or when a
+	* dated file name rolled over. Never throws.
+	*/
+	async afterWrite() {
+		let fileName;
+		try {
+			fileName = this.fileName;
+		} catch {
+			return;
+		}
+		const rolledOver = this.lastFileName !== void 0 && this.lastFileName !== fileName;
+		this.lastFileName = fileName;
+		if (!rolledOver && !this.retentionDue) return;
+		this.retentionDue = false;
+		await this.prune();
+	}
+	/**
+	* Apply `retention` to every directory this channel writes to.
+	*/
+	async pruneFiles() {
+		const retention = this.config("retention");
+		if (!retention || retention.maxFiles === void 0 && retention.maxAgeDays === void 0) return;
+		try {
+			const matcher = this.retentionMatcher(retention);
+			if (!matcher) return;
+			const activeFile = `${this.fileName}.${this.extension}`;
+			for (const directory of await this.retentionDirectories()) await this.pruneDirectory(directory, matcher, retention, activeFile);
+		} catch (error) {
+			this.reportRetentionError(error, this.storagePath);
+		}
+	}
+	/**
+	* The expression a file name must match to be pruned, or `undefined` when
+	* none can be derived (a function `fileName` without `retention.match`).
+	*/
+	retentionMatcher(retention) {
+		if (retention.match) return new RegExp(retention.match.source, retention.match.flags.replace(/[gy]/g, ""));
+		const pattern = this.fileNamePattern;
+		if (typeof pattern === "function") {
+			if (!this.missingMatchReported) {
+				this.missingMatchReported = true;
+				this.reportRetentionError(/* @__PURE__ */ new Error("FileLog retention needs `retention.match` when `fileName` is a function; no files were pruned"), this.storagePath);
+			}
+			return;
+		}
+		const name = this.baseName;
+		const fileSource = pattern === void 0 ? escapeRegExp(name) : fileNamePatternSource(pattern, name);
+		const rotateName = this.config("rotateFileName") ?? "{YYYY}-{MM}-{DD}";
+		const rotateSource = typeof rotateName === "function" ? ".+" : fileNamePatternSource(rotateName, name);
+		return new RegExp(`^${fileSource}(?:-${rotateSource}-\\d{13,})?\\.${escapeRegExp(this.extension)}$`);
+	}
+	/**
+	* The log directory, or each group directory when `groupBy` is set.
+	*/
+	async retentionDirectories() {
+		let directories = [this.storagePath];
+		const depth = this.config("groupBy")?.length ?? 0;
+		for (let level = 0; level < depth; level++) {
+			const next = [];
+			for (const directory of directories) {
+				const entries = await fs.promises.readdir(directory, { withFileTypes: true }).catch((error) => {
+					if (error.code !== "ENOENT") this.reportRetentionError(error, directory);
+					return [];
+				});
+				for (const entry of entries) if (entry.isDirectory()) next.push(path.join(directory, entry.name));
+			}
+			directories = next;
+		}
+		return directories;
+	}
+	/**
+	* Remove the matching files of one directory that `retention` no longer
+	* keeps. Each failure is reported and the rest still run.
+	*/
+	async pruneDirectory(directory, matcher, retention, activeFile) {
+		let names;
+		try {
+			names = await fs.promises.readdir(directory);
+		} catch (error) {
+			if (error.code !== "ENOENT") this.reportRetentionError(error, directory);
+			return;
+		}
+		const candidates = [];
+		for (const name of names) {
+			if (name === activeFile || !matcher.test(name)) continue;
+			const filePath = path.join(directory, name);
+			try {
+				const stats = await fs.promises.stat(filePath);
+				if (stats.isFile()) candidates.push({
+					filePath,
+					name,
+					modifiedAt: stats.mtimeMs
+				});
+			} catch (error) {
+				if (error.code !== "ENOENT") this.reportRetentionError(error, filePath);
+			}
+		}
+		candidates.sort((a, b) => b.modifiedAt - a.modifiedAt || (a.name < b.name ? 1 : -1));
+		const keep = retention.maxFiles === void 0 ? Infinity : retention.maxFiles - (names.includes(activeFile) ? 1 : 0);
+		const oldestKept = retention.maxAgeDays === void 0 ? -Infinity : Date.now() - retention.maxAgeDays * DAY_MS;
+		for (const [index, candidate] of candidates.entries()) {
+			if (index < keep && candidate.modifiedAt >= oldestKept) continue;
+			try {
+				await fs.promises.unlink(candidate.filePath);
+			} catch (error) {
+				if (error.code !== "ENOENT") this.reportRetentionError(error, candidate.filePath);
+			}
+		}
+	}
+	/**
+	* Send a retention failure to the channel error handler.
+	*/
+	reportRetentionError(error, target) {
+		this.reportError(error, {
+			type: "error",
+			module: "logger",
+			action: "retention",
+			message: `Log retention failed for ${target}`
+		});
 	}
 	/**
 	* Synchronously flush messages
@@ -222,14 +389,17 @@ var FileLog = class extends LogChannel {
 		if (this.messages.length === 0 || this.isWriting || !this.isInitialized) return;
 		this.isWriting = true;
 		if (this.messagedShouldBeGrouped) return await this.writeGroupedMessagesToFile();
-		await this.checkAndRotateFile();
 		try {
-			await this.write(this.filePath, this.content);
+			const filePath = this.filePath;
+			await this.checkAndRotateFile(filePath);
+			await this.write(filePath, this.content);
 			this.onSave();
 		} catch (error) {
 			console.error("Failed to write log:", error);
 			this.isWriting = false;
+			return;
 		}
+		await this.afterWrite();
 	}
 	/**
 	* Write grouped messages to the file
@@ -238,11 +408,11 @@ var FileLog = class extends LogChannel {
 		this.prepareGroupedMessages();
 		for (const [key, groupMessages] of Object.entries(this.groupedMessages)) {
 			const directoryPath = path.join(this.storagePath, key);
-			await ensureDirectoryAsync(directoryPath);
-			const filePath = path.join(directoryPath, `${this.fileName}.${this.extension}`);
-			await this.checkAndRotateFile(filePath);
-			const content = groupMessages.map((message) => message.content).join(EOL) + EOL;
 			try {
+				await ensureDirectoryAsync(directoryPath);
+				const filePath = path.join(directoryPath, `${this.fileName}.${this.extension}`);
+				await this.checkAndRotateFile(filePath);
+				const content = groupMessages.map((message) => message.content).join(EOL) + EOL;
 				await this.write(filePath, content);
 			} catch (error) {
 				console.error("Failed to write log:", error);
@@ -250,6 +420,7 @@ var FileLog = class extends LogChannel {
 		}
 		this.onSave();
 		this.isWriting = false;
+		await this.afterWrite();
 	}
 	/**
 	* Prepare grouped messages
@@ -275,7 +446,17 @@ var FileLog = class extends LogChannel {
 		});
 	}
 };
+/**
+* Reject a `retention` that could never keep or remove anything sensibly.
+*/
+function assertRetention(retention) {
+	if (!retention) return;
+	const { maxFiles, maxAgeDays, match } = retention;
+	if (maxFiles !== void 0 && (!Number.isInteger(maxFiles) || maxFiles < 1)) throw new TypeError("FileLog retention.maxFiles must be a positive integer");
+	if (maxAgeDays !== void 0 && (!Number.isFinite(maxAgeDays) || maxAgeDays <= 0)) throw new TypeError("FileLog retention.maxAgeDays must be a positive number");
+	if (match !== void 0 && !(match instanceof RegExp)) throw new TypeError("FileLog retention.match must be a RegExp");
+}
 
 //#endregion
-export { FileLog };
+export { DAILY_FILE_NAME, FileLog, HOURLY_FILE_NAME, ROTATE_FILE_NAME };
 //# sourceMappingURL=file-log.mjs.map