@n8io/baseline-logger 3.1.1 → 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 +2 -4
- package/dist/index.d.ts +21 -6
- package/dist/index.js +24 -2
- package/dist/logger-err-serialize.d.ts +8 -0
- package/dist/logger-err-serialize.js +4 -0
- package/package.json +12 -11
package/README.md
CHANGED
|
@@ -6,13 +6,11 @@
|
|
|
6
6
|
pnpm add @n8io/baseline-logger
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
<p align="center"><img src="https://raw.githubusercontent.com/n8io/baseline/main/docs/readme/error-tracking-report.svg" width="880" alt="One logger.error call with a DatabaseError whose message holds an email address. The log line carries its class as msg, its code, constraint, stack frames and trace id; loggerErrorListen hands the same error to an Error report. The message is struck out of both."></p>
|
|
10
|
-
|
|
11
9
|
## Guarantees
|
|
12
10
|
|
|
13
11
|
| You get | How |
|
|
14
12
|
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
-
| **One logger everywhere** | Every
|
|
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. |
|
|
16
14
|
| **Credentials never logged** | Fields named like credentials (`authorization`, `cookie`, `password`, `token` and others) log as `[Redacted]`, also one level down and in headers. |
|
|
17
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. |
|
|
18
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. |
|
|
@@ -30,7 +28,7 @@ logger.error({ err: error }, "Postgres idle client error");
|
|
|
30
28
|
logger.error({ err: error });
|
|
31
29
|
```
|
|
32
30
|
|
|
33
|
-
|
|
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.
|
|
34
32
|
|
|
35
33
|
## Reference
|
|
36
34
|
|
package/dist/index.d.ts
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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/
|
|
73
|
-
|
|
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.
|
|
4
|
-
"description": "
|
|
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
|
}
|