@warlock.js/logger 4.1.15 → 4.2.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog — @warlock.js/logger
+
+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.
+
+## [Unreleased]
+
+## 4.2.0
+
+### Added
+
+- `log.flush()` — awaitable async counterpart to `flushSync()`. Drains every channel that implements `flush()` via `Promise.allSettled` with per-channel isolation, so one channel's failure can't break shutdown. `FileLog` / `JSONFileLog` implement it; `ConsoleLog` writes synchronously and doesn't need it.
+- `SentryLog` channel — forwards entries to Sentry. `eventLevels` (`fatal` / `error` / `warn` by default) become events (`captureException` for `Error` messages, `captureMessage` otherwise); every other level becomes a breadcrumb. `module` / `action` are tags, `context` is a structured Sentry context. `@sentry/node` is an **optional peer**, lazily imported — pass an existing `client` or `options`.
+- `log.fatal()` + `fatal` log level — ranked strictly above `error` for unrecoverable failures (failed bootstrap, `uncaughtException`). Does not auto-flush or exit; caller decides.
+- `ConsoleLog` renders `fatal` with a `☠` icon on a bright-red background and bold red-bright message, distinct from `error`'s `✗`.
+
+### Changed
+
+- `captureAnyUnhandledRejection()` now escalates `uncaughtException` to `log.fatal` (was `log.error`). Node terminates the process by default, so it's semantically fatal — makes "page only on fatal" alerting clean. `unhandledRejection` stays at `error`.
+- `LoggingData.type` is now typed as `LogLevel` (was a duplicated inline union — code-standards cleanup).
+- `LogContract` and the `LogChannel` base now expose an optional `flush?()` alongside the existing `flushSync?()`.
+
+### Fixed
+
+- `@sentry/node` is now referenced only via local minimal types + an indirect dynamic import, so source-served consumers (the package's `main` → `./src/index.ts`) no longer get a `TS2307: Cannot find module '@sentry/node'` when they (correctly) don't install the optional peer. Proven by pruning the SDK and running the full suite + `tsc --noEmit` clean.
+
+## 4.1.15
+
+- Baseline — per-package changelog tracking starts at this version.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hassan Zohdy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,145 +1,146 @@
-# @warlock.js/logger
-
-Structured, multi-channel logging for Node.js — five severity levels, a clean three-argument API, and full TypeScript support. Non-blocking by default; synchronous flush on demand.
-
-## Install
-
-```bash
-npm install @warlock.js/logger
-# or
-yarn add @warlock.js/logger
-```
-
-## 30-second tour
-
-```ts
-import { log, ConsoleLog, FileLog } from "@warlock.js/logger";
-
-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"));
-```
-
-The logger starts with no channels — nothing is printed or written until you register at least one.
-
-## The module · action · message pattern
-
-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");
-```
-
-Pass an object instead of positional args when you need `context` metadata:
-
-```ts
-await log.error({
-  module: "orders",
-  action: "checkout",
-  message: "Card declined",
-  context: { orderId: "ord_9f2a", amount: 4999 },
-});
-```
-
-## Levels
-
-`debug` · `info` · `warn` · `error` · `success` — each has a shorthand method on the `log` singleton (and on every `Logger` instance).
-
-## 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 |
-
-All three share the `BasicLogConfigurations` options (`levels`, `filter`, `dateFormat`); `FileLog` / `JSONFileLog` add storage, chunking, rotation, and grouping options on top.
-
-## `log` and `Logger`
-
-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.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.
-
-## Graceful shutdown
-
-`FileLog` and `JSONFileLog` buffer entries. Tell the logger to drain them on exit:
-
-```ts
-log.configure({
-  channels: [new ConsoleLog(), new FileLog({ chunk: "daily" })],
-  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
-});
-```
-
-Signal events flush then re-raise (so Node exits with its normal signal semantics); `beforeExit` flushes in place. For full control, call `log.flushSync()` manually inside your own handler instead.
-
-## Capturing unhandled errors
-
-```ts
-import { captureAnyUnhandledRejection } from "@warlock.js/logger";
-
-captureAnyUnhandledRejection();
-```
-
-Registers process-level handlers for `unhandledRejection` and `uncaughtException`, forwarding both to `log.error("app", ...)`. Call once at startup, after channels are registered.
-
-## Custom channels
-
-Extend `LogChannel` and implement `log(data)`:
-
-```ts
-import { LogChannel, type LoggingData } from "@warlock.js/logger";
-
-export class SlackLog extends LogChannel<{ webhookUrl: string }> {
-  public name = "slack";
-
-  public async log(data: LoggingData) {
-    if (!this.shouldBeLogged(data)) return;
-    await fetch(this.config("webhookUrl"), {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        text: `[${data.type}] [${data.module}][${data.action}]: ${data.message}`,
-      }),
-    });
-  }
-}
-```
-
-Set `terminal = true` on the class if your channel writes to a TTY — otherwise ANSI codes are auto-stripped from string messages.
-
-## Full documentation
-
-The complete guide lives in the project docs:
-
-- Getting Started
-- Configuration
-- Channels (ConsoleLog, FileLog, JSONFileLog)
-- Lifecycle & Flushing
-- Capturing Unhandled Errors
-- Custom Channels
-- Recipes
-- API Reference
-- Types
-
-## Tests
-
-This package uses Vitest. From the repo root:
-
-```bash
-npx vitest run --root @warlock.js/logger
-```
-
-## License
-
-MIT
+# @warlock.js/logger
+
+Structured, multi-channel logging for Node.js — six severity levels (debug / info / warn / error / success / fatal), a clean three-argument API, and full TypeScript support. Non-blocking by default; synchronous or async flush on demand.
+
+## Install
+
+```bash
+npm install @warlock.js/logger
+# or
+yarn add @warlock.js/logger
+```
+
+## 30-second tour
+
+```ts
+import { log, ConsoleLog, FileLog } from "@warlock.js/logger";
+
+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"));
+```
+
+The logger starts with no channels — nothing is printed or written until you register at least one.
+
+## The module · action · message pattern
+
+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");
+```
+
+Pass an object instead of positional args when you need `context` metadata:
+
+```ts
+await log.error({
+  module: "orders",
+  action: "checkout",
+  message: "Card declined",
+  context: { orderId: "ord_9f2a", amount: 4999 },
+});
+```
+
+## Levels
+
+`debug` · `info` · `warn` · `error` · `success` · `fatal` — each has a shorthand method on the `log` singleton (and on every `Logger` instance). `fatal` is strictly above `error` for unrecoverable failures where the app is going down (failed bootstrap, `uncaughtException`); it does not auto-flush or exit on its own.
+
+## 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 |
+
+All channels share the `BasicLogConfigurations` options (`levels`, `filter`, `dateFormat`); `FileLog` / `JSONFileLog` add storage, chunking, rotation, and grouping options, and `SentryLog` adds `client` / `options` / `eventLevels`.
+
+## `log` and `Logger`
+
+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(...)`.
+- **`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.
+
+## Graceful shutdown
+
+`FileLog` and `JSONFileLog` buffer entries. Tell the logger to drain them on exit:
+
+```ts
+log.configure({
+  channels: [new ConsoleLog(), new FileLog({ chunk: "daily" })],
+  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
+});
+```
+
+Signal events flush then re-raise (so Node exits with its normal signal semantics); `beforeExit` flushes in place. For full control, call `log.flushSync()` (sync) — or `await log.flush()` (async, for network/async channels) — inside your own handler instead.
+
+## Capturing unhandled errors
+
+```ts
+import { captureAnyUnhandledRejection } from "@warlock.js/logger";
+
+captureAnyUnhandledRejection();
+```
+
+Registers process-level handlers for `unhandledRejection` and `uncaughtException`, forwarding both to `log.error("app", ...)`. Call once at startup, after channels are registered.
+
+## Custom channels
+
+Extend `LogChannel` and implement `log(data)`:
+
+```ts
+import { LogChannel, type LoggingData } from "@warlock.js/logger";
+
+export class SlackLog extends LogChannel<{ webhookUrl: string }> {
+  public name = "slack";
+
+  public async log(data: LoggingData) {
+    if (!this.shouldBeLogged(data)) return;
+    await fetch(this.config("webhookUrl"), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: `[${data.type}] [${data.module}][${data.action}]: ${data.message}`,
+      }),
+    });
+  }
+}
+```
+
+Set `terminal = true` on the class if your channel writes to a TTY — otherwise ANSI codes are auto-stripped from string messages.
+
+## Full documentation
+
+The complete guide lives in the project docs:
+
+- Getting Started
+- Configuration
+- Channels (ConsoleLog, FileLog, JSONFileLog, SentryLog)
+- Lifecycle & Flushing
+- Capturing Unhandled Errors
+- Custom Channels
+- Recipes
+- API Reference
+- Types
+
+## Tests
+
+This package uses Vitest. From the repo root:
+
+```bash
+npx vitest run --root @warlock.js/logger
+```
+
+## License
+
+MIT