Skip to content
Merged

5.5.0 #396

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,16 @@

All notable changes to this project are documented here. This project adheres to [Semantic Versioning](https://semver.org/).

## [5.5.0] - 2026-11-09

### Added
- **Hex colors in `pretty.styles`** (#394) — `"#00ff00"` / `"#0f0"` set the text color and `"bg#00ff00"` the background, alone or mixed with named tokens (`["#ff8800", "bold"]`). Browsers apply them as CSS; terminals get 24-bit ANSI colors. Thanks @jan-bukowski for the request.

### Fixed
- **Masking applies to values serialized through `toJSON()`** (#395) — with `mask` configured, an object whose `toJSON()` builds its output from data that is not a plain own property (a closure, Immutable.js collections, classes with `#private` fields) was written unmasked in JSON output and in a pretty error's non-Error `cause`. A class whose `toJSON()` reads `#private` fields made the whole JSON line disappear. `toJSON()` now runs on the original value and its result is masked at the same path, so `keys`, `paths` and `regex` all apply. If it throws, the object's own masked properties are serialized instead. Thanks @trackoor.
- **JSON render failures are reported** — when a value cannot be serialized (a `toJSON()` or getter that throws), the default JSON output still skips the line, but now reports it on `console.error` instead of dropping it silently.
- **Unknown `pretty.styles` tokens no longer throw** — with `pretty.style` on, a token outside the palette made every log call throw a `TypeError`. It now leaves the value unstyled.

## [5.4.0] - 2026-10-18

### Added
Expand Down
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -501,6 +501,7 @@ Masking is leak-proof by construction:
- `regex` patterns are always applied **globally**: every occurrence in a string is redacted, whether or not you wrote the `g` flag.
- Shared references and circular structures resolve to the same *masked* clone, so a secret can never escape through a second reference to the same object.
- `keys` and `regex` also apply **inside `Map` and `Set`** contents (`paths` does not descend into them).
- **Values with `toJSON()` are masked by their serialized form.** Class instances (including ones with `#private` fields), Immutable.js collections and other objects that serialize through `toJSON()` have it called on the original value, and its result is masked like any other value at the same path, so the JSON line and a pretty error `cause` show the masked result. Pretty output of the object itself still inspects its own (masked) properties.
- **Errors are masked like any other object.** A logged `Error`, top-level or nested, is replaced by a masked clone and the caller's instance stays untouched. `regex` covers the `message` and the `<name>: <message>` header of a V8-style stack, but never the frames, so a broad pattern cannot corrupt `line:col` positions. `keys`, `regex` and `paths` cover every other own property (`code`, `extensions`, ...) and the `cause` chain. `keys` skips `name`, `message` and `stack`, so `keys: ["name"]` does not blank every error, while `paths` can still target them (`paths: ["message"]`).

The `censor` option controls *how* a **`paths`-matched** value is replaced (`keys`- and `regex`-matched values always use `placeholder`, with one exception below):
Expand Down Expand Up @@ -835,6 +836,12 @@ const log = new Logger({
});
```

Besides the named palette tokens (`red`, `blueBright`, `bgYellow`, `bold`, ...), a style can be a hex color: `"#00ff00"` or `"#0f0"` sets the text color and `"bg#00ff00"` the background. Browsers apply it as CSS; terminals get a 24-bit ANSI color, which most modern terminals support. Hex tokens mix freely with named ones (`["#ff8800", "bold"]`), and a token tslog does not recognize leaves the value unstyled.

```typescript
new Logger({ pretty: { styles: { fileNameWithLine: "#00ff00", logLevelName: { WARN: ["bg#ff8800", "bold"] } } } });
```

Route levels to specific console methods with `pretty.levelMethod`:

```typescript
Expand Down
2 changes: 1 addition & 1 deletion RECIPES.md
Original file line number Diff line number Diff line change
Expand Up @@ -569,7 +569,7 @@ const log = new Logger({
shortTime: (meta) => meta.date.toISOString().slice(11, 23), // "01:02:03.004" (UTC; check `pretty.timeZone` for local)
reqId: (meta) => String((meta as { requestId?: string }).requestId ?? "-"), // runInContext / middleware fields land on meta
},
styles: { shortTime: "blackBright", reqId: "cyan" },
styles: { shortTime: "blackBright", reqId: "#ff8800" }, // palette token or hex color ("#rgb", "#rrggbb", "bg#rrggbb")
},
});
```
Expand Down
1,633 changes: 1,116 additions & 517 deletions docs/package-lock.json

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ import { Logger, createLogger, log } from "tslog"; // class + typed-custom-level
## Settings are GROUPED (no flat keys)
- `type`, `name`, `minLevel: "INFO"` (name or 0..6), `prefix: ["[api]"]` (args prepended to every call, concatenated down the sub-logger chain; use `bindings` for JSON fields, `prefix` for message text), `strictConfig: true` (throw `TslogConfigError` on unknown/typo'd/v4-flat keys; without it they warn in dev with a did-you-mean).
- `persistLevel: true` (browser-only) — persist runtime `setMinLevel()` changes in `localStorage` and restore them on reload; key name via `persistLevelKey`; no-op outside browsers.
- `mask: { keys: ["password","apiKey","token","prompt"], paths: ["user.password","*.token"], caseInsensitive, regex, censor, placeholder: "[***]" }` — redact secrets/PII/prompts by key, dotted path, or regex. Regexes always apply globally (no `g` flag needed); keys/regex also mask inside `Map`/`Set` contents; shared/circular references resolve to the same masked clone. Errors are masked too: `regex` on `message` and on the V8 stack header (never on the frames), `keys`/`regex`/`paths` on every other own property and down the `cause` chain. `keys` skips `name`/`message`/`stack`, `paths` can target them.
- `json: { messageKey, levelKey, timeKey, errorKey, time: "iso"|"epoch"|false|fn }` (`time` shapes the top-level timestamp; `_logMeta.date` stays UTC ISO), `pretty: { template, timeZone, style, levelMethod, passObjectsNatively, inspectOptions }`, `stack: { capture: "off"|"lazy"|"auto"|"full" }`, `meta: { property, attachContext }`. `pretty.template` reshapes the log line via `{{placeholders}}` — `{{logLevelName}}`, `{{name}}`, `{{filePathWithLine}}`, `{{dateIsoStr}}`, or date parts `{{yyyy}}.{{mm}}.{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}` — and `stack.capture: "auto"` (the pretty default; json defaults to `"off"`) captures frames only when the template renders a code position. `pretty.placeholders: { token: (meta, pretty) => string | number }` adds custom `{{token}}`s to `pretty.template` (styled via `pretty.styles.token`; built-in names reserved; only referenced tokens run, a throw renders empty; meta template only, never JSON), e.g. `placeholders: { shortTime: (meta) => meta.date.toISOString().slice(11, 23) }`. `pretty.passObjectsNatively` hands non-Error args to the console by reference (collapsible objects in browser DevTools; pair with `levelMethod` for native warn/error stack groups) — default TRUE in real browsers, false elsewhere; set `false` for log-time snapshots (raw references show post-mutation state when expanded) or text-matchable output (DevTools filter/console-capture only match the rendered string); `pretty.inspectOptions.breakLength: Infinity` keeps inspected objects on one line for log aggregators.
- `mask: { keys: ["password","apiKey","token","prompt"], paths: ["user.password","*.token"], caseInsensitive, regex, censor, placeholder: "[***]" }` — redact secrets/PII/prompts by key, dotted path, or regex. Regexes always apply globally (no `g` flag needed); keys/regex also mask inside `Map`/`Set` contents; shared/circular references resolve to the same masked clone. Errors are masked too: `regex` on `message` and on the V8 stack header (never on the frames), `keys`/`regex`/`paths` on every other own property and down the `cause` chain. `keys` skips `name`/`message`/`stack`, `paths` can target them. Objects with `toJSON()` (classes with `#private` fields, Immutable.js) are masked by the result of their own `toJSON()`.
- `json: { messageKey, levelKey, timeKey, errorKey, time: "iso"|"epoch"|false|fn }` (`time` shapes the top-level timestamp; `_logMeta.date` stays UTC ISO), `pretty: { template, timeZone, style, levelMethod, passObjectsNatively, inspectOptions }`, `stack: { capture: "off"|"lazy"|"auto"|"full" }`, `meta: { property, attachContext }`. `pretty.template` reshapes the log line via `{{placeholders}}` — `{{logLevelName}}`, `{{name}}`, `{{filePathWithLine}}`, `{{dateIsoStr}}`, or date parts `{{yyyy}}.{{mm}}.{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}` — and `stack.capture: "auto"` (the pretty default; json defaults to `"off"`) captures frames only when the template renders a code position. `pretty.placeholders: { token: (meta, pretty) => string | number }` adds custom `{{token}}`s to `pretty.template` (styled via `pretty.styles.token`; built-in names reserved; only referenced tokens run, a throw renders empty; meta template only, never JSON), e.g. `placeholders: { shortTime: (meta) => meta.date.toISOString().slice(11, 23) }`. `pretty.styles` values are palette tokens (`"red"`, `"bold"`, `"bgYellow"`), hex colors (`"#00ff00"`/`"#0f0"` text, `"bg#00ff00"` background — CSS in browsers, 24-bit ANSI in terminals), arrays of them, or per-level maps (`{ "*": ..., WARN: ... }`). `pretty.passObjectsNatively` hands non-Error args to the console by reference (collapsible objects in browser DevTools; pair with `levelMethod` for native warn/error stack groups) — default TRUE in real browsers, false elsewhere; set `false` for log-time snapshots (raw references show post-mutation state when expanded) or text-matchable output (DevTools filter/console-capture only match the rendered string); `pretty.inspectOptions.breakLength: Infinity` keeps inspected objects on one line for log aggregators.
- Source-mapped error positions (Node/Bun/Deno, not browser): `_logMeta.path` and pretty error stacks resolve through a source map back to the original `.ts` file/line/column when one is discoverable, automatically outside production (`NODE_ENV !== "production"`); force with `TSLOG_SOURCE_MAPS=on`/`off`. Flat and indexed (`sections`) maps both work — incl. Turbopack/Next.js dev, TanStack Start (Vite), webpack, Rollup, esbuild, tsc output.
- `clock: () => Date` — injectable clock (deterministic tests, offset stamping); inherited by sub-loggers; a throwing/invalid clock is ignored.

Expand Down
Loading
Loading