@warlock.js/logger 5.29.0 → 5.31.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to `@warlock.js/logger` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.31.0 - 2026-10-18
+
+### Upgrading
+
+- **BREAKING:** `FileLog`/`JSONFileLog` dated file names are ISO dates that sort by name: `chunk: "daily"` writes `YYYY-MM-DD.log` (was `DD-MM-YYYY.log`) and `chunk: "hourly"` writes `YYYY-MM-DD-HH.log` (was `DD-MM-YYYY-HH-00-00-am.log`). Size-rotated archives default to `<file name>-YYYY-MM-DD-<epoch ms>`. After upgrading, a running daily channel starts a new file under the new name. To keep the old names, set `fileName: "{DD}-{MM}-{YYYY}"` (daily) and `rotateFileName: "{DD}-{MM}-{YYYY}"`. Tools that find logs by name (shippers, cron cleanups) need the new pattern; `retention` does not remove files with the old names.
+- `rotateFileName` is now a `{YYYY}`/`{MM}`/`{DD}`/`{HH}`/`{mm}`/`{name}` pattern or a function of the rotation date, not a Day.js format. A value without tokens is used as is, as before; a Day.js format such as `"DD-MM-YYYY"` was always written literally and still is — use `"{DD}-{MM}-{YYYY}"`.
+
+### Added
+
+- `FileLog` `fileName` option: a pattern (`"app-{YYYY}-{MM}-{DD}"`, tokens `{YYYY}` `{MM}` `{DD}` `{HH}` `{mm}` `{name}` in local time) or a `(date) => string` function, evaluated at every write; it replaces the chunk's default name. `rotateFileName` takes the same forms and is rendered at each rotation (a getter passed in the config was read once, at construction, so every archive kept the boot date). Exported `FileNameOption`, `FileLogRetention`, `DAILY_FILE_NAME`, `HOURLY_FILE_NAME` and `ROTATE_FILE_NAME`.
+- `FileLog` `retention: { maxFiles?, maxAgeDays?, match? }`: removes old log files on boot and whenever the channel starts a new file (a size rotation or a dated name rolling over), plus `channel.prune()` on demand. It only considers files in the log directory (each group directory with `groupBy`) whose names match the channel's file name pattern, keeps the file being written, and reports failures to `onChannelError` instead of throwing. A function `fileName` needs `retention.match`. Invalid `maxFiles`/`maxAgeDays` throw a `TypeError` at construction.
+- `LogChannel.reportError(error, entry)` and `setErrorReporter(reporter)` (type `ChannelErrorReporter`): a channel reports failures outside `log()` to the `onChannelError` handler of the logger it was added to (`addChannel`, `setChannels`, `configure({ channels })`), or one stderr line without one.
+- `escapeLogValue(value, { maxLength? })` makes client-controlled text safe inside a log line: CR/LF/tab become visible `\r`/`\n`/`\t`, other control characters (NUL, DEL, C1, U+2028/U+2029) become `\uXXXX`, ANSI escape sequences are removed, and `maxLength` cuts with a `…[truncated]` marker. A user agent or form field can no longer forge entries in console or file logs.
+- Skills demonstrate email masking inside text, channel-error observation and bounded asynchronous log drains.
+
+### Fixed
+
+- With `groupBy`, size rotation renames the group file that grew too large instead of the ungrouped top-level file.
+- A file name that throws while a buffer is written (a `fileName` function, or an overridden `fileName` getter) is reported as a failed write instead of leaving the channel stuck in its writing state; later writes go through.
+
+## 5.30.0 - 2026-10-16
+
+### Upgrading
+
+- **BREAKING (types):** `log.info/warn/error/debug/success/fatal/log/assert` and the function `timer()` returns now return the logger synchronously instead of `Promise<this>`. Remove `await` before log calls (it is harmless but pointless) and any `.then()` chained on one; code that needs the write to finish calls `await log.flush()`. `warlock upgrade --from 5.29 --to 5.31.0` removes the `await`s and lists chained `.then()` calls (codemod `logger-sync-calls`).
+
+### Changed
+
+- Logging is fire-and-forget: level methods no longer return a promise, so `@typescript-eslint/no-floating-promises` no longer flags every call site.
+- `log.flush()` drains every channel concurrently: each waits for its own in-flight async deliveries (including entries logged while the flush runs), then runs its `flush()`, so a hung network channel no longer holds up the file channel.
+- `log.flush({ timeout })` is bounded: it resolves after `timeout` ms (default 5000, `DEFAULT_FLUSH_TIMEOUT_MS`; `Infinity` waits without a limit) and reports each channel still draining to the channel error handler. Before, one delivery that never settled made `flush()` (and a graceful shutdown awaiting it) wait forever.
+- `maskEmailsInText` cuts text longer than `MASK_EMAILS_MAX_LENGTH` (16,384 characters) and marks the cut, so masking a huge cache key or message has a bounded cost.
+
+### Added
+
+- `log.onChannelError(handler)` / `configure({ onChannelError })` and the `ChannelErrorHandler` type: receives a channel's sync throw or async rejection from `log()`, a redaction that threw, or a timed-out `flush()`. Default: one stderr line. The handler may be async; a rejection is swallowed.
+- `maskEmail(address)` and `maskEmailsInText(text)`: mask email addresses (`m***@example.com`) inside message strings and cache keys, which key-based redaction cannot reach. Core's mail logs and the cache drivers' key logs use them.
+
+### Fixed
+
+- A channel whose `log()` rejected became an unhandled rejection (looping through `captureAnyUnhandledRejection`), and one that threw synchronously stopped delivery to the channels after it; both are now isolated and reported to the channel error handler.
+- A redaction that threw (a `censor` function that fails on an unexpected value) threw at the call site and skipped the remaining channels. A channel's own redaction failure is now isolated like any channel failure; a logger-wide one drops the entry (it is never delivered unredacted) and is reported to the channel error handler.
+- An async `onChannelError` handler that rejected became an unhandled rejection.
+- **Security:** `maskEmailsInText` backtracked quadratically on long runs of address-like characters with no domain (about 11 s on 75 KB), and it runs on cache keys built from request input. Its pattern is now bounded and linear. It also masks addresses with letters from any script (`jöhn@exämple.de`), and `maskEmail` no longer keeps half of a surrogate pair.
+
 ## 5.29.0 - 2026-10-01
 
 ### Changed
@@ -75,6 +120,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 
 - Lockstep release maintenance and dependency refresh.
+
 ## 5.20.0 - 2026-09-24
 
 ### Changed
@@ -164,7 +210,7 @@ changelogs.
 
 ### Security
 
-- **Secrets are now redacted by default. This is a behavior change — logs that previously showed these values in cleartext will now show `[REDACTED]`.** Redaction used to be a *tool* (`redact.paths`, entirely opt-in): unless an application configured it, a `password` in `context`, an `authorization` header, or an `apiKey` on a logged `Error` reached every sink — console, log file, JSON log file, Sentry — verbatim. Protection existed only where every call site had been configured correctly, with no signal when one hadn't. It is now a *default*.
+- **Secrets are now redacted by default. This is a behavior change — logs that previously showed these values in cleartext will now show `[REDACTED]`.** Redaction used to be a _tool_ (`redact.paths`, entirely opt-in): unless an application configured it, a `password` in `context`, an `authorization` header, or an `apiKey` on a logged `Error` reached every sink — console, log file, JSON log file, Sentry — verbatim. Protection existed only where every call site had been configured correctly, with no signal when one hadn't. It is now a _default_.
 
   A built-in denylist (`DEFAULT_REDACT_KEYS`) censors matching keys at any depth of `context`, `message`, and an `Error`'s own enumerable properties, applied at the same logger-wide choke point as `redact.paths` — so every channel inherits it, including custom ones. The set covers passwords, shared secrets, tokens (access/refresh/id/CSRF/session), API and private keys, HTTP credential headers (`authorization`, `x-api-key`, `cookie`, `set-cookie`), session IDs, connection strings, and high-sensitivity financial PII (card numbers, CVV, SSN, IBAN).
 
@@ -179,7 +225,7 @@ changelogs.
 
   Paths are evaluated before keys, so a function `censor` on an explicit path still receives the original value rather than a mask, and that leaf is not censored twice.
 
-  Known residual gaps, unchanged by this release and documented on `applyRedact`: secrets interpolated into a `message` *string* (`` `token=${t}` ``) cannot be reached by either matcher; `Map` / `Set` / `Buffer` contents are not traversed; and properties exposed only via getters or non-enumerable descriptors are not walked, so an HTTP client that hides its request config behind a getter can still slip through. Enumerable ones — axios's `.config` / `.response`, which carry the outgoing `Authorization` header — *are* now covered.
+  Known residual gaps, unchanged by this release and documented on `applyRedact`: secrets interpolated into a `message` _string_ (`` `token=${t}` ``) cannot be reached by either matcher; `Map` / `Set` / `Buffer` contents are not traversed; and properties exposed only via getters or non-enumerable descriptors are not walked, so an HTTP client that hides its request config behind a getter can still slip through. Enumerable ones — axios's `.config` / `.response`, which carry the outgoing `Authorization` header — _are_ now covered.
 
 ### Fixed
 

package/README.md

@@ -23,13 +23,10 @@ yarn add @warlock.js/logger
 ```ts
 import { log, ConsoleLog, FileLog } from "@warlock.js/logger";
 
-log.setChannels([
-  new ConsoleLog(),
-  new FileLog({ chunk: "daily" }),
-]);
+log.setChannels([new ConsoleLog(), new FileLog({ chunk: "daily" })]);
 
-await log.info("users", "register", "New user created");
-await log.error("payments", "charge", new Error("Card declined"));
+log.info("users", "register", "New user created");
+log.error("payments", "charge", new Error("Card declined"));
 ```
 
 The logger starts with no channels — nothing is printed or written until you register at least one.
@@ -39,15 +36,15 @@ The logger starts with no channels — nothing is printed or written until you r
 Every call carries three pieces of context. Modules and actions become searchable keys in file and JSON channels:
 
 ```ts
-await log.info("auth", "login", "User signed in");
-await log.warn("api", "rateLimitApproaching", "80% of quota used");
-await log.success("payments", "captured", "Payment of $49.99 captured");
+log.info("auth", "login", "User signed in");
+log.warn("api", "rateLimitApproaching", "80% of quota used");
+log.success("payments", "captured", "Payment of $49.99 captured");
 ```
 
 Pass an object instead of positional args when you need `context` metadata:
 
 ```ts
-await log.error({
+log.error({
   module: "orders",
   action: "checkout",
   message: "Card declined",
@@ -61,12 +58,12 @@ await log.error({
 
 ## Built-in channels
 
-| Channel | Name | Purpose |
-|---|---|---|
-| `ConsoleLog` | `"console"` | Colorized terminal output |
-| `FileLog` | `"file"` | Plain-text files, optional chunking + rotation + grouping |
-| `JSONFileLog` | `"fileJson"` | Structured JSON files — ideal for aggregators |
-| `SentryLog` | `"sentry"` | Forwards to Sentry (events + breadcrumbs); needs the optional `@sentry/node` peer |
+| Channel       | Name         | Purpose                                                                           |
+| ------------- | ------------ | --------------------------------------------------------------------------------- |
+| `ConsoleLog`  | `"console"`  | Colorized terminal output                                                         |
+| `FileLog`     | `"file"`     | Plain-text files, optional chunking + rotation + grouping                         |
+| `JSONFileLog` | `"fileJson"` | Structured JSON files — ideal for aggregators                                     |
+| `SentryLog`   | `"sentry"`   | Forwards to Sentry (events + breadcrumbs); needs the optional `@sentry/node` peer |
 
 All channels share the `BasicLogConfigurations` options (`levels`, `filter`, `dateFormat`); `FileLog` / `JSONFileLog` add storage, chunking, rotation, and grouping options, and `SentryLog` adds `client` / `options` / `eventLevels`.
 
@@ -74,7 +71,7 @@ All channels share the `BasicLogConfigurations` options (`levels`, `filter`, `da
 
 The package exports one default singleton and one class:
 
-- **`log`** — a pre-instantiated `Logger`. Day-to-day logging *and* configuration both go through it: `log.info(...)`, `log.configure(...)`, `log.flush()` / `log.flushSync()`, `log.addChannel(...)`.
+- **`log`** — a pre-instantiated `Logger`. Day-to-day logging _and_ configuration both go through it: `log.info(...)`, `log.configure(...)`, `log.flush()` / `log.flushSync()`, `log.addChannel(...)`.
 - **`Logger`** — the class. Use it when you need an isolated logger (libraries, sandboxes, parallel test suites).
 
 `log` is a `Logger` instance, not a function — every level shortcut and configuration method is reachable on it. The bare-callable `log(data)` form was removed; use `log.log(data)` for the data-object form, or `log.info(...)` / `log.error(...)` / etc. for the positional form.