Skip to content

v2 beta 9: drop use of serialize-error package directly #145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cuzzlor merged 1 commit into from
Apr 29, 2026
Merged

v2 beta 9: drop use of serialize-error package directly #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
40 changes: 20 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,22 +8,22 @@ A set of [winston](https://github.com/winstonjs/winston) [formats](https://githu
npm install @makerx/node-winston
```

`winston`, `logform`, `winston-transport`, `triple-beam`, `es-toolkit` and `serialize-error` are declared as peer dependencies, so bring your own versions (>=3, >=2, >=4, >=1, >=1, >=13 respectively).
`winston`, `logform`, `winston-transport`, `triple-beam` and `es-toolkit` are declared as peer dependencies, so bring your own versions (>=3, >=2, >=4, >=1, >=1 respectively).

Requires Node.js `>=22.12` (for flag-free `require(esm)` support, needed by `serialize-error`'s ESM-only publish).
Requires Node.js `>=20`.

## Migrating from v1

Breaking changes:

- The `lodash` dependency has been replaced with `es-toolkit` as a peer dependency.
- Node.js `>=22.12` is required (for flag-free `require(esm)`, needed by `serialize-error`'s ESM-only publish).
- **Error serialisation has changed.** `serialize-error` is now a peer dependency, and `serializeError` delegates to it instead of v1's hand-rolled `{ message, stack, ...rest }` shape. The serialised wire format now includes `name`, follows `cause` chains, walks own enumerable properties, and handles circular references — so any consumer asserting against the exact v1 shape will need to update.
- Node.js `>=20` is required.
- **Error serialisation has changed.** `serializeError` now captures `name` (in addition to `message` and `stack`), follows `cause` chains, walks own enumerable properties, captures `AggregateError.errors`, stringifies `BigInt` values, replaces `Buffer` and stream values with sentinel strings, and is safe against circular references. Any consumer asserting against v1's exact `{ message, stack, ...rest }` shape will need to update.
- **Errors nested in structured metadata are now serialised on every transport, not just the Console transport.** v1 only ran `serializableErrorReplacer` inside the Console's `format.json`, so custom transports received the raw `Error` instance (with non-enumerable `message`/`stack` hidden). v2 prepends the new `serializeErrorFormat` at the logger level, which walks the full info tree and substitutes plain objects before any transport sees them. If a custom transport relied on receiving an `Error` instance, switch it to read the serialised shape — or pass `errorSerializer` to `createLogger` (or `serializer` to `serializeErrorFormat` directly) to plug in your own transformation.
- `omitPaths` now applies at the logger level and affects every transport, not just the Console transport. If you added custom transports expecting the un-omitted object, move omit handling into that transport's format.
- A new `audit` level sits between `warn` and `info`. Loggers configured at `level: 'info'` (or more verbose) will now include `audit` messages; loggers at `level: 'warn'` or higher still filter them out.
- Pass a custom `levels` map via `loggerOptions` to opt out of the default level set (including `audit`); the returned logger type narrows to your keys.
- Submodule deep-imports (e.g. `@makerx/node-winston/redact-format`, `@makerx/node-winston/serialize-error`) are no longer exported. The package's `exports` field declares a single `.` entry; every public format, helper and type is re-exported from the root, so import them from `@makerx/node-winston` directly. The `./serialize-error` subpath in particular has no replacement: `serializeError` is still re-exported from the root, but for direct use of the underlying serializer, import from the [`serialize-error`](https://www.npmjs.com/package/serialize-error) peer dependency — we no longer wrap it in a dedicated subpath.
- Submodule deep-imports (e.g. `@makerx/node-winston/redact-format`, `@makerx/node-winston/serialize-error`) are no longer exported. The package's `exports` field declares a single `.` entry; every public format, helper and type is re-exported from the root, so import them from `@makerx/node-winston` directly.

New functionality:

Expand All @@ -47,20 +47,20 @@ Formats are applied in two layers:

### Options

| Option | Type | Description |
| ---------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consoleFormat` | `'json' \| 'pretty'` | Output format for the Console transport. `json` (default) for deployed environments, `pretty` for colourised YAML during local development. |
| `consoleOptions` | `ConsoleTransportOptions` | Options forwarded to the Console transport (e.g. `silent`, per-transport `level`). The `format` property is managed by this library. |
| `consoleFormats` | `Format[]` | Extra formats appended to the Console transport's format chain, before the final `json`/`pretty` step. Applies to the Console transport only. |
| `transports` | `Transport[]` | Additional winston transports attached alongside the Console transport. |
| `omitPaths` | `string[]` | Dot-notation paths to remove from every log entry. Applied at the logger level, so affects all transports. |
| `redactPaths` | `string[]` | Dot-notation paths whose values are replaced with `redactedValue`. Applied at the logger level, so affects all transports. |
| `redactedValue` | `string` | Replacement value used by `redactPaths`. Defaults to `'<redacted>'`. |
| `flatten` | `boolean` | When `true`, serialises every top-level value on the log info to a JSON string, producing a flat `{ key: string }` shape for transports that expect scalar values (e.g. OTEL + Azure Log Analytics). |
| `flattenReplacer` | `(key, value) => any` | Optional `JSON.stringify` replacer used when `flatten` serialises each top-level value. |
| `errorSerializer` | `ErrorSerializer` | Custom serializer applied to every `Error` instance at the logger level (via `serializeErrorFormat`) and as the Console transport's `format.json` replacer. Defaults to the library's `serializeError`, which delegates to [`serialize-error`](https://www.npmjs.com/package/serialize-error). |
| `mapAuditLevelForOtel` | `boolean` | When `true`, rewrites the triple-beam `LEVEL` from `audit` to `info` and copies the original onto `logLevel` for OTEL compatibility. See [Shipping the audit level via OpenTelemetry](#shipping-the-audit-level-via-opentelemetry). |
| `loggerOptions` | `LoggerOptions` | Winston logger options (e.g. `level`, `defaultMeta`). A `format` supplied here is appended after the library's logger-level formats but still runs before `flatten` when enabled. |
| Option | Type | Description |
| ---------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consoleFormat` | `'json' \| 'pretty'` | Output format for the Console transport. `json` (default) for deployed environments, `pretty` for colourised YAML during local development. |
| `consoleOptions` | `ConsoleTransportOptions` | Options forwarded to the Console transport (e.g. `silent`, per-transport `level`). The `format` property is managed by this library. |
| `consoleFormats` | `Format[]` | Extra formats appended to the Console transport's format chain, before the final `json`/`pretty` step. Applies to the Console transport only. |
| `transports` | `Transport[]` | Additional winston transports attached alongside the Console transport. |
| `omitPaths` | `string[]` | Dot-notation paths to remove from every log entry. Applied at the logger level, so affects all transports. |
| `redactPaths` | `string[]` | Dot-notation paths whose values are replaced with `redactedValue`. Applied at the logger level, so affects all transports. |
| `redactedValue` | `string` | Replacement value used by `redactPaths`. Defaults to `'<redacted>'`. |
| `flatten` | `boolean` | When `true`, serialises every top-level value on the log info to a JSON string, producing a flat `{ key: string }` shape for transports that expect scalar values (e.g. OTEL + Azure Log Analytics). |
| `flattenReplacer` | `(key, value) => any` | Optional `JSON.stringify` replacer used when `flatten` serialises each top-level value. |
| `errorSerializer` | `ErrorSerializer` | Custom serializer applied to every `Error` instance at the logger level (via `serializeErrorFormat`) and as the Console transport's `format.json` replacer. Defaults to the library's `serializeError`, which captures `name`/`message`/`stack`/`code`/`cause`/`errors` even when non-enumerable, walks own enumerable properties, and is safe against circular references. |
| `mapAuditLevelForOtel` | `boolean` | When `true`, rewrites the triple-beam `LEVEL` from `audit` to `info` and copies the original onto `logLevel` for OTEL compatibility. See [Shipping the audit level via OpenTelemetry](#shipping-the-audit-level-via-opentelemetry). |
| `loggerOptions` | `LoggerOptions` | Winston logger options (e.g. `level`, `defaultMeta`). A `format` supplied here is appended after the library's logger-level formats but still runs before `flatten` when enabled. |

### Log levels

Expand Down Expand Up @@ -309,7 +309,7 @@ try {

`createLogger` solves this with two complementary mechanisms:

- `serializeErrorFormat` runs at the logger level and walks the log info, replacing any `Error` instance (at any depth) with a plain, JSON-serializable object (via the [`serialize-error`](https://www.npmjs.com/package/serialize-error) package). This applies to every transport.
- `serializeErrorFormat` runs at the logger level and walks the log info, replacing any `Error` instance (at any depth) with a plain, JSON-serializable object via the library's `serializeError`. This applies to every transport.
- `serializableErrorReplacer` is passed to the Console transport's final `format.json()` as a safety net — [logform](https://github.com/winstonjs/logform) uses [safe-stable-stringify](https://www.npmjs.com/package/safe-stable-stringify), which accepts a replacer, so any `Error` that slips through is still serialised correctly.

```ts
Expand Down
61 changes: 0 additions & 61 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading