@n8io/baseline-logger 3.1.0 → 3.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,17 +1,21 @@
1
1
  # @n8io/baseline-logger
2
2
 
3
- The one [pino](https://getpino.io) logger every app and package logs through: JSON to stdout, with credentials redacted and errors reduced to a safe shape.
3
+ **One logger that keeps credentials and error messages out**: JSON to stdout, credentials redacted, and an error logged only as its class, code and stack frames, never its message.
4
4
 
5
5
  ```sh
6
6
  pnpm add @n8io/baseline-logger
7
7
  ```
8
8
 
9
- ## Exports
9
+ ## Guarantees
10
10
 
11
- - `logger`: the one logger, typed as the package's own `Logger` (`fatal`, `error`, `warn`, `info`, `debug`, `trace` and `level`), so the library behind it can change without touching a caller. Fields named like credentials (`authorization`, `cookie`, `password`, `token` and others) are logged as `[Redacted]`, also one level down and in headers.
12
- - `Logger` and `LoggerMethod`: the types of `logger` and of one level's call, `(fields, message?)` or `(message)`. There is no `child`, no printf-style arguments and no way to set `level`; the level comes from `LOG_LEVEL`.
13
- - `loggerErrorListen(listener)` and `LoggerErrorListener`: calls `listener` with each error logged at error or fatal (an `err` field, or an Error passed first), inside the log call, so it sees the caller's active trace; returns a function that stops it. A listener that throws is skipped and the log line still goes out, and an error a listener logs is not heard again. Listeners live on `globalThis`, so two copies of this Package share them. A level that `LOG_LEVEL` turns off reaches no listener. `@n8io/baseline-error-tracking` reports errors this way.
14
- - `@n8io/baseline-logger/err-serialize`: `loggerErrSerialize(value)` and `LoggerErr`. An error leaves the process only as its class name, `code`, `constraint` and stack, down the `cause` chain; never its message, which can hold input text. `logger` uses it for every `err`.
11
+ | You get | How |
12
+ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13
+ | **One logger everywhere** | Every Project and Package imports the same `logger`, typed as this Package's own `Logger`, so the library behind it can change without touching a caller. |
14
+ | **Credentials never logged** | Fields named like credentials (`authorization`, `cookie`, `password`, `token` and others) log as `[Redacted]`, also one level down and in headers. |
15
+ | **No message text** | An error leaves only as its class name, `code`, `constraint` and stack frames, down the `cause` chain. With no message given, `msg` is the class name. |
16
+ | **Errors reach error tracking** | `loggerErrorListen` hears each error logged at error or fatal, inside the log call, so it sees the caller's trace. |
17
+ | **A listener cannot break logging** | A listener that throws is skipped and the line still goes out; an error a listener logs is not heard again. |
18
+ | **Logs join the trace** | With `@n8io/baseline-telemetry` preloaded, each record also goes out as an OTLP log with the active trace id, and the stdout line gains `trace_id` and `span_id`. |
15
19
 
16
20
  ## Example
17
21
 
@@ -24,7 +28,18 @@ logger.error({ err: error }, "Postgres idle client error");
24
28
  logger.error({ err: error });
25
29
  ```
26
30
 
27
- ## Needs
31
+ Nothing to configure in tests. Assert on what the code returns, not on log lines; a test that must read a line captures stdout for its run and restores it in `onTestFinished`, as the Template's `src/error-tracking-open.test.ts` does.
28
32
 
29
- - Env: `LOG_LEVEL` (`fatal`, `error`, `warn`, `info`, `debug`, `trace` or `silent`; default `info`).
30
- - With `@n8io/baseline-telemetry` preloaded, each record also goes out as an OTLP log with the active trace id.
33
+ ## Reference
34
+
35
+ <details><summary><b>Exports</b></summary>
36
+
37
+ | Export | Does |
38
+ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
39
+ | `logger` | The one logger: `fatal`, `error`, `warn`, `info`, `debug`, `trace` and `level`. Credential fields are redacted as above. |
40
+ | `Logger`, `LoggerMethod` | The types of `logger` and of one level's call, `(fields, message?)` or `(message)`. There is no `child`, no printf-style arguments and no way to set `level`; the level comes from `LOG_LEVEL`. |
41
+ | `loggerErrorListen(listener)`, `LoggerErrorListener` | Calls `listener` with each error logged at error or fatal (an `err` field, or an Error passed first), inside the log call, so it sees the caller's active trace; returns a function that stops it. A listener that throws is skipped and the log line still goes out, and an error a listener logs is not heard again. Listeners live on `globalThis`, so two copies of this Package share them. A level that `LOG_LEVEL` turns off reaches no listener, nor does an `err` logged beside a `msg` field. `@n8io/baseline-error-tracking` reports errors this way. |
42
+ | `loggerErrSerialize(value)`, `LoggerErr` (`/err-serialize`) | The safe shape. An error leaves the process only as its class name, `code`, `constraint` and stack, down the `cause` chain (10 deep at most); never its message, which can hold input text. `logger` uses it for every `err`, and telemetry and error tracking build on it. |
43
+ </details>
44
+
45
+ **Needs** `LOG_LEVEL` (`fatal`, `error`, `warn`, `info`, `debug`, `trace` or `silent`; default `info`). Runs on [pino](https://getpino.io); nothing in the API names it.
package/dist/index.d.ts CHANGED
@@ -1,11 +1,16 @@
1
- type LoggerErrorListener = (error: unknown) => void;
2
- /** Calls `listener` with every error logged at error or fatal; the returned function stops it. */
3
- export declare const loggerErrorListen: (listener: LoggerErrorListener) => (() => void);
4
- export type LoggerMethod = {
1
+ /**
2
+ * One level's call: fields then a message, a caught value alone, or a message alone. An `err`
3
+ * field, or an Error passed first, is logged in the safe shape of loggerErrSerialize.
4
+ */
5
+ type LoggerMethod = {
5
6
  (fields: unknown, message?: string): void;
6
7
  (message: string): void;
7
8
  };
8
- export type Logger = {
9
+ /**
10
+ * What every Project and Package may call. The library behind it can change without touching a
11
+ * caller.
12
+ */
13
+ type Logger = {
9
14
  readonly level: string;
10
15
  fatal: LoggerMethod;
11
16
  error: LoggerMethod;
@@ -14,5 +19,15 @@ export type Logger = {
14
19
  debug: LoggerMethod;
15
20
  trace: LoggerMethod;
16
21
  };
22
+ /** The one logger: JSON to stdout, level from `LOG_LEVEL` (default `info`). A
23
+ * `LOG_LEVEL` that is not a level throws a `TypeError` on import. */
17
24
  export declare const logger: Logger;
18
- export type { LoggerErrorListener };
25
+ /**
26
+ * Who hears each error the logger logs at error or fatal: error tracking, without its callers
27
+ * changing. A listener runs inside the log call, so it sees the caller's active trace, and must
28
+ * return at once and never throw; one that throws is skipped.
29
+ */
30
+ type LoggerErrorListener = (error: unknown) => void;
31
+ /** Calls `listener` with every error logged at error or fatal; the returned function stops it. */
32
+ export declare const loggerErrorListen: (listener: LoggerErrorListener) => (() => void);
33
+ export type { Logger, LoggerErrorListener, LoggerMethod };
package/dist/index.js CHANGED
@@ -1,5 +1,23 @@
1
1
  import { loggerErrSerialize } from "./logger-err-serialize.js";
2
2
  import { pino } from "pino";
3
+ // src/logger-level-assert.ts
4
+ const loggerLevels = [
5
+ "fatal",
6
+ "error",
7
+ "warn",
8
+ "info",
9
+ "debug",
10
+ "trace",
11
+ "silent"
12
+ ];
13
+ /**
14
+ * Returns `level` when it is one the logger knows, so a typo in `LOG_LEVEL` fails at import with
15
+ * this Package's message, not the vendor's. Throws a `TypeError` otherwise.
16
+ */
17
+ const loggerLevelAssert = (level) => {
18
+ if (!loggerLevels.includes(level)) throw new TypeError(`LOG_LEVEL must be one of ${loggerLevels.join(", ")}, not "${level}"`);
19
+ return level;
20
+ };
3
21
  // src/logger-error-listen.ts
4
22
  const listenersKey = Symbol.for("@n8io/baseline-logger.errorListeners");
5
23
  const registry = globalThis;
@@ -13,6 +31,7 @@ const loggerErrorListen = (listener) => {
13
31
  listeners.delete(listener);
14
32
  };
15
33
  };
34
+ /** Hands `error` to every listener; the logger calls it, nothing else does. */
16
35
  const loggerErrorEmit = (error) => {
17
36
  if (emitting) return;
18
37
  emitting = true;
@@ -51,6 +70,7 @@ const errFind = (first) => {
51
70
  if (typeof first === "object" && first !== null && "err" in first && !("msg" in first)) return first.err;
52
71
  };
53
72
  const levelError = 50;
73
+ /** pino's options for the one logger: redaction, the safe `err` shape and the error listeners. */
54
74
  const loggerOptionsCreate = (level) => ({
55
75
  hooks: { logMethod(args, method, level) {
56
76
  const [first, second] = args;
@@ -69,6 +89,8 @@ const loggerOptionsCreate = (level) => ({
69
89
  },
70
90
  serializers: { err: loggerErrSerialize }
71
91
  });
72
- // src/index.ts
73
- const logger = pino(loggerOptionsCreate(process.env.LOG_LEVEL || "info"));
92
+ // src/logger.ts
93
+ /** The one logger: JSON to stdout, level from `LOG_LEVEL` (default `info`). A
94
+ * `LOG_LEVEL` that is not a level throws a `TypeError` on import. */
95
+ const logger = pino(loggerOptionsCreate(loggerLevelAssert(process.env.LOG_LEVEL || "info")));
74
96
  export { logger, loggerErrorListen };
@@ -1,3 +1,7 @@
1
+ /**
2
+ * The only error shape that leaves the process: class name, code, constraint and stack frames,
3
+ * down the cause chain. Never message or detail, because both can hold input text.
4
+ */
1
5
  export type LoggerErr = {
2
6
  cause?: LoggerErr;
3
7
  code?: number | string;
@@ -5,4 +9,8 @@ export type LoggerErr = {
5
9
  stack?: string;
6
10
  type: string;
7
11
  };
12
+ /**
13
+ * Turns any caught value into the safe shape: an Error's class name, `code`, `constraint` and
14
+ * stack frames, down the `cause` chain (10 deep at most); anything else as its type.
15
+ */
8
16
  export declare const loggerErrSerialize: (value: unknown) => LoggerErr;
@@ -22,5 +22,9 @@ const errSerialize = (value, depth) => {
22
22
  if (value.cause !== void 0 && depth < causeDepthMax) shape.cause = errSerialize(value.cause, depth + 1);
23
23
  return shape;
24
24
  };
25
+ /**
26
+ * Turns any caught value into the safe shape: an Error's class name, `code`, `constraint` and
27
+ * stack frames, down the `cause` chain (10 deep at most); anything else as its type.
28
+ */
25
29
  const loggerErrSerialize = (value) => errSerialize(value, 0);
26
30
  export { loggerErrSerialize };
package/package.json CHANGED
@@ -1,21 +1,17 @@
1
1
  {
2
2
  "name": "@n8io/baseline-logger",
3
- "version": "3.1.0",
4
- "description": "The one pino logger every baseline app and package logs through.",
5
- "type": "module",
3
+ "version": "3.1.2",
4
+ "description": "One JSON logger for a Project and its Packages that keeps credentials and error messages out of every line.",
6
5
  "license": "MIT",
6
+ "type": "module",
7
+ "engines": {
8
+ "node": ">=26"
9
+ },
7
10
  "repository": {
8
11
  "type": "git",
9
12
  "url": "git+https://github.com/n8io/baseline.git",
10
13
  "directory": "packages/logger"
11
14
  },
12
- "engines": {
13
- "node": ">=26"
14
- },
15
- "files": [
16
- "dist",
17
- "README.md"
18
- ],
19
15
  "exports": {
20
16
  ".": {
21
17
  "types": "./dist/index.d.ts",
@@ -26,6 +22,10 @@
26
22
  "default": "./dist/logger-err-serialize.js"
27
23
  }
28
24
  },
25
+ "files": [
26
+ "dist",
27
+ "README.md"
28
+ ],
29
29
  "publishConfig": {
30
30
  "access": "public",
31
31
  "registry": "https://registry.npmjs.org"
@@ -36,6 +36,7 @@
36
36
  "scripts": {
37
37
  "build": "tsdown",
38
38
  "check": "tsc --noEmit && pnpm pack --out dist/package.tgz && publint dist/package.tgz --strict && attw dist/package.tgz --profile esm-only",
39
- "test": "vitest run"
39
+ "test": "vitest run",
40
+ "test:unit": "vitest run"
40
41
  }
41
42
  }