@warlock.js/logger 5.24.0 → 5.25.0

package/skills/filter-log-entries/SKILL.md

@@ -1,120 +1,120 @@
----
-name: filter-log-entries
-description: 'Drop log entries — per-channel levels whitelist, per-channel filter predicate, logger-wide setMinLevel(level) fast path. Triggers: `levels`, `filter`, `minLevel`, `log.setMinLevel`, `shouldBeLogged`, `LoggingData`, `LogLevel`; "silence a noisy module", "route errors to a dedicated file", "raise global severity floor", "drop debug logs in prod"; typical import `import { log } from "@warlock.js/logger"`. Skip: custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; competing libs `pino.levels`, `winston.format.filter`, `debug` env var.'
----
-
-# Filtering — `levels` + `filter` predicate + `minLevel`
-
-Every channel can silently drop entries it doesn't care about. Three mechanisms stack: a logger-wide `minLevel` floor (cheapest), then per-channel `levels` whitelist, then per-channel `filter` predicate.
-
-## 1. `levels` — the per-channel whitelist
-
-```ts
-new FileLog({ levels: ["error", "warn"] });
-// debug/info/success entries → skipped
-// error/warn entries → written
-```
-
-- Omitting `levels` (or passing `[]`) means **allow all six**.
-- No regex / no range — it's a literal whitelist of `LogLevel` strings.
-
-## 2. `filter` — the per-channel custom predicate
-
-```ts
-new ConsoleLog({
-  filter: (data) => data.module !== "healthcheck",
-});
-// Every entry is passed to the predicate; return false → skip.
-```
-
-- `data` is the full `LoggingData`: `{ type, module, action, message, context? }`.
-- Predicate runs **after** `levels` — an entry blocked by `levels` never reaches `filter`.
-
-## 3. `minLevel` — the logger-wide severity floor
-
-For the common "drop everything below X" case, skip the per-channel `levels` array and use the logger-wide fast path:
-
-```ts
-log.setMinLevel("info");
-// debug entries are dropped before fan-out — no channel ever sees them.
-
-log.configure({ minLevel: "warn" });   // shorthand inside configure()
-```
-
-Severity ordering: `debug < info ≈ success < warn < error < fatal`. `success` is treated as informational severity — `setMinLevel("warn")` drops it. `fatal` is strictly above `error`, so `setMinLevel("fatal")` admits only fatal entries (handy for "page me only on fatal" routing).
-
-Pass `undefined` to clear:
-
-```ts
-log.setMinLevel(undefined);   // accept everything again
-```
-
-This runs **before** the channel loop — cheaper than per-channel `levels` filters when you want a uniform floor. Per-channel `levels` and `filter` still run on top for channels that need a tighter or differently-shaped rule.
-
-## Combining — real patterns
-
-### Route errors to a dedicated file
-
-```ts
-log.setChannels([
-  new ConsoleLog(),
-  new FileLog({
-    name: "errors",
-    levels: ["error", "warn"],
-    chunk: "daily",
-  }),
-]);
-// ConsoleLog sees everything; errors.log only grows with warnings and errors.
-```
-
-### Silence a noisy module
-
-```ts
-new ConsoleLog({
-  filter: (data) => data.module !== "socket.io",
-});
-```
-
-### Keep the dev terminal focused
-
-```ts
-// Only surface the subsystem you're actively working on
-new ConsoleLog({
-  filter: (data) => data.module === "auth",
-});
-```
-
-### Errors always pass, info only for one module
-
-```ts
-new ConsoleLog({
-  filter: (data) => data.type === "error" || data.module === "payments",
-});
-```
-
-## Where filtering happens
-
-`LogChannel.shouldBeLogged(data)` runs both checks in order:
-
-```ts
-// levels check — fast path
-if (this.config("levels")?.length && !this.config("levels").includes(data.type)) return false;
-
-// filter predicate — only runs if levels allowed it
-const filter = this.config("filter");
-if (filter) return filter(data);
-
-return true;
-```
-
-If you extend `LogChannel` to write a custom channel, call `this.shouldBeLogged(data)` first thing inside your `log(data)` method — you inherit both mechanisms for free. See [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md).
-
-## Logger-wide custom filtering — not a thing
-
-There is no `logger.setGlobalFilter()`. Each channel filters itself. If you want the same predicate everywhere, pass it to every channel constructor (or wrap your channels in a helper).
-
-## Performance note
-
-Filters run on **every** entry per channel. A synchronous, cheap predicate is fine. Avoid `await` inside — the channel receives a fully-formed `LoggingData` and the filter is sync-only (type: `(data: LoggingData) => boolean`).
-
-The `minLevel` check is the fastest of the three (single comparison before fan-out), so prefer it when "drop everything below X uniformly" matches your need.
+---
+name: filter-log-entries
+description: 'Drop log entries — per-channel levels whitelist, per-channel filter predicate, logger-wide setMinLevel(level) fast path. Triggers: `levels`, `filter`, `minLevel`, `log.setMinLevel`, `shouldBeLogged`, `LoggingData`, `LogLevel`; "silence a noisy module", "route errors to a dedicated file", "raise global severity floor", "drop debug logs in prod"; typical import `import { log } from "@warlock.js/logger"`. Skip: custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; competing libs `pino.levels`, `winston.format.filter`, `debug` env var.'
+---
+
+# Filtering — `levels` + `filter` predicate + `minLevel`
+
+Every channel can silently drop entries it doesn't care about. Three mechanisms stack: a logger-wide `minLevel` floor (cheapest), then per-channel `levels` whitelist, then per-channel `filter` predicate.
+
+## 1. `levels` — the per-channel whitelist
+
+```ts
+new FileLog({ levels: ["error", "warn"] });
+// debug/info/success entries → skipped
+// error/warn entries → written
+```
+
+- Omitting `levels` (or passing `[]`) means **allow all six**.
+- No regex / no range — it's a literal whitelist of `LogLevel` strings.
+
+## 2. `filter` — the per-channel custom predicate
+
+```ts
+new ConsoleLog({
+  filter: (data) => data.module !== "healthcheck",
+});
+// Every entry is passed to the predicate; return false → skip.
+```
+
+- `data` is the full `LoggingData`: `{ type, module, action, message, context? }`.
+- Predicate runs **after** `levels` — an entry blocked by `levels` never reaches `filter`.
+
+## 3. `minLevel` — the logger-wide severity floor
+
+For the common "drop everything below X" case, skip the per-channel `levels` array and use the logger-wide fast path:
+
+```ts
+log.setMinLevel("info");
+// debug entries are dropped before fan-out — no channel ever sees them.
+
+log.configure({ minLevel: "warn" });   // shorthand inside configure()
+```
+
+Severity ordering: `debug < info ≈ success < warn < error < fatal`. `success` is treated as informational severity — `setMinLevel("warn")` drops it. `fatal` is strictly above `error`, so `setMinLevel("fatal")` admits only fatal entries (handy for "page me only on fatal" routing).
+
+Pass `undefined` to clear:
+
+```ts
+log.setMinLevel(undefined);   // accept everything again
+```
+
+This runs **before** the channel loop — cheaper than per-channel `levels` filters when you want a uniform floor. Per-channel `levels` and `filter` still run on top for channels that need a tighter or differently-shaped rule.
+
+## Combining — real patterns
+
+### Route errors to a dedicated file
+
+```ts
+log.setChannels([
+  new ConsoleLog(),
+  new FileLog({
+    name: "errors",
+    levels: ["error", "warn"],
+    chunk: "daily",
+  }),
+]);
+// ConsoleLog sees everything; errors.log only grows with warnings and errors.
+```
+
+### Silence a noisy module
+
+```ts
+new ConsoleLog({
+  filter: (data) => data.module !== "socket.io",
+});
+```
+
+### Keep the dev terminal focused
+
+```ts
+// Only surface the subsystem you're actively working on
+new ConsoleLog({
+  filter: (data) => data.module === "auth",
+});
+```
+
+### Errors always pass, info only for one module
+
+```ts
+new ConsoleLog({
+  filter: (data) => data.type === "error" || data.module === "payments",
+});
+```
+
+## Where filtering happens
+
+`LogChannel.shouldBeLogged(data)` runs both checks in order:
+
+```ts
+// levels check — fast path
+if (this.config("levels")?.length && !this.config("levels").includes(data.type)) return false;
+
+// filter predicate — only runs if levels allowed it
+const filter = this.config("filter");
+if (filter) return filter(data);
+
+return true;
+```
+
+If you extend `LogChannel` to write a custom channel, call `this.shouldBeLogged(data)` first thing inside your `log(data)` method — you inherit both mechanisms for free. See [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md).
+
+## Logger-wide custom filtering — not a thing
+
+There is no `logger.setGlobalFilter()`. Each channel filters itself. If you want the same predicate everywhere, pass it to every channel constructor (or wrap your channels in a helper).
+
+## Performance note
+
+Filters run on **every** entry per channel. A synchronous, cheap predicate is fine. Avoid `await` inside — the channel receives a fully-formed `LoggingData` and the filter is sync-only (type: `(data: LoggingData) => boolean`).
+
+The `minLevel` check is the fastest of the three (single comparison before fan-out), so prefer it when "drop everything below X uniformly" matches your need.

package/skills/flush-logs-on-shutdown/SKILL.md

@@ -1,117 +1,117 @@
----
-name: flush-logs-on-shutdown
-description: 'Drain buffered channels before exit — log.flushSync() or log.configure({autoFlushOn: [''SIGINT'', ''SIGTERM'', ''beforeExit'']}) installs handlers that re-raise the signal. Triggers: `log.flush`, `log.flushSync`, `autoFlushOn`, `enableAutoFlush`, `disableAutoFlush`, `SIGINT`, `SIGTERM`, `beforeExit`; "drain logs before exit", "await log.flush() before process.exit", "drain async or network channels on shutdown", "wire SIGTERM for container shutdown", "my logs never showed after a crash", "graceful shutdown logging"; typical import `import { log, FileLog } from "@warlock.js/logger"`. Skip: error capture — `@warlock.js/logger/capture-unhandled-errors/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; competing `pino.final`, `winston.end`; native `process.on(''exit'')`.'
----
-
-# Lifecycle — flushing buffered channels before exit
-
-`FileLog` and `JSONFileLog` buffer entries in memory. A process that exits without draining loses the buffer.
-
-## The easy way — `autoFlushOn`
-
-Tell the logger which process events should trigger a flush. It installs the handlers for you.
-
-```ts
-log.configure({
-  channels: [new ConsoleLog(), new FileLog({ chunk: "daily" })],
-  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
-});
-```
-
-### What each event does
-
-| Event | Behavior |
-|---|---|
-| `SIGINT` / `SIGTERM` / `SIGHUP` / `SIGBREAK` / `SIGUSR2` | Flush → remove this handler → re-raise the signal so Node's default exit code runs (e.g. 130 for SIGINT). |
-| `beforeExit` | Flush in place. Node continues its natural exit. |
-
-### Default recommendation
-
-`["SIGINT", "SIGTERM", "beforeExit"]` covers:
-- Local `Ctrl+C` (SIGINT)
-- Container orchestrators (`docker stop`, Kubernetes sending SIGTERM)
-- Natural exit (Node finished all work)
-
-Add `"SIGHUP"` if you care about terminal disconnects. Add `"SIGUSR2"` if you use nodemon or pm2 restart.
-
-### Idempotency
-
-Calling `enableAutoFlush` twice **replaces** previous handlers — it does not stack. `disableAutoFlush()` removes every handler this logger instance registered; safe to call when nothing is registered.
-
-## The manual way — your own handler
-
-Use this when you need async work (close an HTTP server, drain a queue) **before** flushing:
-
-```ts
-async function gracefulShutdown() {
-  await httpServer.close();
-  await queue.drain();
-  log.flushSync();          // still sync — guarantees disk write before exit
-  process.exit(0);
-}
-
-process.once("SIGINT", gracefulShutdown);
-process.once("SIGTERM", gracefulShutdown);
-```
-
-**If you go manual for a signal, skip it in `autoFlushOn`** — otherwise both handlers fire and ours re-raises the signal mid-way through your async work.
-
-## Async drain — `log.flush()`
-
-`flushSync()` blocks the event loop with synchronous I/O. That's correct for the file channels and required inside the handlers `autoFlushOn` installs (a re-raised signal kills the process before any promise could settle). But a channel whose delivery is **async** — a network transport, an async disk write — can't drain synchronously. For those, `await` the async sibling on a graceful path you control:
-
-```ts
-async function gracefulShutdown() {
-  await httpServer.close();
-  await log.flush();        // awaits every channel's async flush() to completion
-  process.exit(0);
-}
-
-process.once("SIGTERM", gracefulShutdown);
-```
-
-`log.flush()` fans out to every channel that implements `flush()` and awaits them together (`Promise.allSettled`). Each channel is isolated — one channel's flush rejecting neither aborts the others nor escapes as an unhandled rejection. Channels without `flush()` are skipped.
-
-| | `flushSync()` | `flush()` |
-|---|---|---|
-| I/O | synchronous — blocks the loop | asynchronous — awaited |
-| Safe in a re-raising signal handler | yes | no — the signal exits before the promise settles |
-| Used by `autoFlushOn` | yes | no |
-| Reach for it when | file channels, last-resort durability | network/async channels, manual `await` before `process.exit` |
-| `FileLog` / `JSONFileLog` | ✓ | ✓ (async write) |
-
-`autoFlushOn` always uses `flushSync()` — signal re-raising can't wait on a promise. If a channel needs async delivery on shutdown, drive `await log.flush()` from your own handler and leave that signal out of `autoFlushOn`.
-
-## What `flushSync()` actually does
-
-```ts
-log.flushSync();
-// For every registered channel:
-//   if (channel.flushSync) channel.flushSync();
-```
-
-- Synchronous I/O — blocks the event loop.
-- Channels without `flushSync` (e.g. `ConsoleLog` — nothing to flush) are skipped silently.
-- Works with and without `groupBy` on `FileLog` / `JSONFileLog`.
-- No-op if every channel's buffer is empty.
-
-`ConsoleLog` has no `flushSync` — it writes synchronously on every entry. `FileLog` and `JSONFileLog` both implement it.
-
-## Unhandled errors
-
-The `uncaughtException` path in [`captureAnyUnhandledRejection()`](@warlock.js/logger/capture-unhandled-errors/SKILL.md) already runs a best-effort, time-bounded `log.flush()` before its own `process.exit(1)`, so the fatal entry drains without extra wiring (and `process.exit()` skips `beforeExit`, so a `beforeExit` handler would not fire on that path anyway). Still set `autoFlushOn` for the *other* shutdown routes — `"SIGINT"` / `"SIGTERM"` and a natural `"beforeExit"` — so those don't lose the last buffered batch.
-
-```ts
-log.configure({
-  channels: [new FileLog({ levels: ["error"] })],
-  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
-});
-
-captureAnyUnhandledRejection();
-```
-
-## What NOT to do
-
-- **Don't `await` inside a signal handler you wrote yourself and then call `flushSync`** — if an async step rejects, you skip the flush. Wrap in `try { await x } finally { log.flushSync(); process.exit(1); }`.
-- **Don't call `process.exit()` inside `autoFlushOn` handlers** — signal handlers here already re-raise the signal. Forcing an exit breaks exit codes.
-- **Don't rely on the 5-second flush interval for shutdown safety.** It's a throughput optimization, not a durability guarantee.
+---
+name: flush-logs-on-shutdown
+description: 'Drain buffered channels before exit — log.flushSync() or log.configure({autoFlushOn: [''SIGINT'', ''SIGTERM'', ''beforeExit'']}) installs handlers that re-raise the signal. Triggers: `log.flush`, `log.flushSync`, `autoFlushOn`, `enableAutoFlush`, `disableAutoFlush`, `SIGINT`, `SIGTERM`, `beforeExit`; "drain logs before exit", "await log.flush() before process.exit", "drain async or network channels on shutdown", "wire SIGTERM for container shutdown", "my logs never showed after a crash", "graceful shutdown logging"; typical import `import { log, FileLog } from "@warlock.js/logger"`. Skip: error capture — `@warlock.js/logger/capture-unhandled-errors/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; competing `pino.final`, `winston.end`; native `process.on(''exit'')`.'
+---
+
+# Lifecycle — flushing buffered channels before exit
+
+`FileLog` and `JSONFileLog` buffer entries in memory. A process that exits without draining loses the buffer.
+
+## The easy way — `autoFlushOn`
+
+Tell the logger which process events should trigger a flush. It installs the handlers for you.
+
+```ts
+log.configure({
+  channels: [new ConsoleLog(), new FileLog({ chunk: "daily" })],
+  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
+});
+```
+
+### What each event does
+
+| Event | Behavior |
+|---|---|
+| `SIGINT` / `SIGTERM` / `SIGHUP` / `SIGBREAK` / `SIGUSR2` | Flush → remove this handler → re-raise the signal so Node's default exit code runs (e.g. 130 for SIGINT). |
+| `beforeExit` | Flush in place. Node continues its natural exit. |
+
+### Default recommendation
+
+`["SIGINT", "SIGTERM", "beforeExit"]` covers:
+- Local `Ctrl+C` (SIGINT)
+- Container orchestrators (`docker stop`, Kubernetes sending SIGTERM)
+- Natural exit (Node finished all work)
+
+Add `"SIGHUP"` if you care about terminal disconnects. Add `"SIGUSR2"` if you use nodemon or pm2 restart.
+
+### Idempotency
+
+Calling `enableAutoFlush` twice **replaces** previous handlers — it does not stack. `disableAutoFlush()` removes every handler this logger instance registered; safe to call when nothing is registered.
+
+## The manual way — your own handler
+
+Use this when you need async work (close an HTTP server, drain a queue) **before** flushing:
+
+```ts
+async function gracefulShutdown() {
+  await httpServer.close();
+  await queue.drain();
+  log.flushSync();          // still sync — guarantees disk write before exit
+  process.exit(0);
+}
+
+process.once("SIGINT", gracefulShutdown);
+process.once("SIGTERM", gracefulShutdown);
+```
+
+**If you go manual for a signal, skip it in `autoFlushOn`** — otherwise both handlers fire and ours re-raises the signal mid-way through your async work.
+
+## Async drain — `log.flush()`
+
+`flushSync()` blocks the event loop with synchronous I/O. That's correct for the file channels and required inside the handlers `autoFlushOn` installs (a re-raised signal kills the process before any promise could settle). But a channel whose delivery is **async** — a network transport, an async disk write — can't drain synchronously. For those, `await` the async sibling on a graceful path you control:
+
+```ts
+async function gracefulShutdown() {
+  await httpServer.close();
+  await log.flush();        // awaits every channel's async flush() to completion
+  process.exit(0);
+}
+
+process.once("SIGTERM", gracefulShutdown);
+```
+
+`log.flush()` fans out to every channel that implements `flush()` and awaits them together (`Promise.allSettled`). Each channel is isolated — one channel's flush rejecting neither aborts the others nor escapes as an unhandled rejection. Channels without `flush()` are skipped.
+
+| | `flushSync()` | `flush()` |
+|---|---|---|
+| I/O | synchronous — blocks the loop | asynchronous — awaited |
+| Safe in a re-raising signal handler | yes | no — the signal exits before the promise settles |
+| Used by `autoFlushOn` | yes | no |
+| Reach for it when | file channels, last-resort durability | network/async channels, manual `await` before `process.exit` |
+| `FileLog` / `JSONFileLog` | ✓ | ✓ (async write) |
+
+`autoFlushOn` always uses `flushSync()` — signal re-raising can't wait on a promise. If a channel needs async delivery on shutdown, drive `await log.flush()` from your own handler and leave that signal out of `autoFlushOn`.
+
+## What `flushSync()` actually does
+
+```ts
+log.flushSync();
+// For every registered channel:
+//   if (channel.flushSync) channel.flushSync();
+```
+
+- Synchronous I/O — blocks the event loop.
+- Channels without `flushSync` (e.g. `ConsoleLog` — nothing to flush) are skipped silently.
+- Works with and without `groupBy` on `FileLog` / `JSONFileLog`.
+- No-op if every channel's buffer is empty.
+
+`ConsoleLog` has no `flushSync` — it writes synchronously on every entry. `FileLog` and `JSONFileLog` both implement it.
+
+## Unhandled errors
+
+The `uncaughtException` path in [`captureAnyUnhandledRejection()`](@warlock.js/logger/capture-unhandled-errors/SKILL.md) already runs a best-effort, time-bounded `log.flush()` before its own `process.exit(1)`, so the fatal entry drains without extra wiring (and `process.exit()` skips `beforeExit`, so a `beforeExit` handler would not fire on that path anyway). Still set `autoFlushOn` for the *other* shutdown routes — `"SIGINT"` / `"SIGTERM"` and a natural `"beforeExit"` — so those don't lose the last buffered batch.
+
+```ts
+log.configure({
+  channels: [new FileLog({ levels: ["error"] })],
+  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
+});
+
+captureAnyUnhandledRejection();
+```
+
+## What NOT to do
+
+- **Don't `await` inside a signal handler you wrote yourself and then call `flushSync`** — if an async step rejects, you skip the flush. Wrap in `try { await x } finally { log.flushSync(); process.exit(1); }`.
+- **Don't call `process.exit()` inside `autoFlushOn` handlers** — signal handlers here already re-raise the signal. Forcing an exit breaks exit codes.
+- **Don't rely on the 5-second flush interval for shutdown safety.** It's a throughput optimization, not a durability guarantee.