@holz/core 0.8.3-rc.154 → 0.8.3-rc.156
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.
|
@@ -1,116 +1,152 @@
|
|
|
1
|
-
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*/
|
|
6
|
-
export
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
/**
|
|
52
|
-
readonly
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
/**
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
*/
|
|
68
|
-
|
|
69
|
-
/**
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
/**
|
|
110
|
-
|
|
111
|
-
/**
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Combine several log processors into a single log processor. Each one is
|
|
3
|
+
* called in sequence. Useful for sending a single log to multiple log
|
|
4
|
+
* destinations.
|
|
5
|
+
*/
|
|
6
|
+
export declare const combine: (processors: Array<LogProcessor>) => LogProcessor;
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Create a new logger. The processor is up to you. There are plugins for
|
|
10
|
+
* filtering, formatting, combining multiple processors together, and more.
|
|
11
|
+
*
|
|
12
|
+
* If you wish to use more than one processor, `combine(...)` them first.
|
|
13
|
+
*/
|
|
14
|
+
export declare const createLogger: (processor: LogProcessor) => Logger;
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Custom values allowed in log context. These values don't have to be JSON.
|
|
18
|
+
* The most common case is errors, which support richer error tracking in
|
|
19
|
+
* backends that support it.
|
|
20
|
+
*
|
|
21
|
+
* This is part of the public API. Backends may use declaration merging to
|
|
22
|
+
* extend the standard attributes. It's recommended to use symbols as keys for
|
|
23
|
+
* custom features, but not required.
|
|
24
|
+
*/
|
|
25
|
+
export declare interface CustomContext {
|
|
26
|
+
/**
|
|
27
|
+
* Error instance associated with the log message. This supports error
|
|
28
|
+
* tracking and shows prominently in visual backends like TTY output.
|
|
29
|
+
*/
|
|
30
|
+
error: Error;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Filter logs based on a filter function. If the function returns true, the
|
|
35
|
+
* log is kept and forwarded onto the next processor, otherwise it is
|
|
36
|
+
* discarded.
|
|
37
|
+
*/
|
|
38
|
+
export declare const filter: (
|
|
39
|
+
/** Returns `true` to forward the log. */
|
|
40
|
+
predicate: (log: Log) => boolean,
|
|
41
|
+
/** Where to send the log if it passes the filter. */
|
|
42
|
+
processor: LogProcessor) => LogProcessor;
|
|
43
|
+
|
|
44
|
+
declare interface JsonContext {
|
|
45
|
+
[key: string]: JsonPrimitive | ReadonlyArray<JsonPrimitive>;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
declare type JsonPrimitive = string | number | boolean | null | undefined;
|
|
49
|
+
|
|
50
|
+
export declare const level: {
|
|
51
|
+
/** A critical failure happened and the program must exit. */
|
|
52
|
+
readonly fatal: 60;
|
|
53
|
+
/** Something failed, but we can keep going. */
|
|
54
|
+
readonly error: 50;
|
|
55
|
+
/** Cause for concern, but we can keep going. */
|
|
56
|
+
readonly warn: 40;
|
|
57
|
+
/** High-level progress updates. */
|
|
58
|
+
readonly info: 30;
|
|
59
|
+
/** Verbose update about events or control flow (usually hidden). */
|
|
60
|
+
readonly debug: 20;
|
|
61
|
+
/** Extremely detailed progress updates (usually hidden). */
|
|
62
|
+
readonly trace: 10;
|
|
63
|
+
};
|
|
64
|
+
|
|
65
|
+
/** A log message where variables are carried as structured data. */
|
|
66
|
+
export declare interface Log {
|
|
67
|
+
/** Unix timestamp. Includes milliseconds. */
|
|
68
|
+
readonly timestamp: number;
|
|
69
|
+
/** The verbatim log message. Should not contain interpolated data. */
|
|
70
|
+
readonly message: string;
|
|
71
|
+
/** Log severity. One of `levels.*`. */
|
|
72
|
+
readonly level: LogLevel;
|
|
73
|
+
/**
|
|
74
|
+
* Where the log message originated. Usually starts with a library or app name,
|
|
75
|
+
* followed by something more specific.
|
|
76
|
+
*
|
|
77
|
+
* @example ['logger-library', 'ConsoleBackend']
|
|
78
|
+
*/
|
|
79
|
+
readonly origin: ReadonlyArray<string>;
|
|
80
|
+
/**
|
|
81
|
+
* Key-value pairs that provide additional context for the log message. If
|
|
82
|
+
* you're tempted to interpolate data into the message, consider using log
|
|
83
|
+
* context instead.
|
|
84
|
+
*
|
|
85
|
+
* These values must be JSON serializable.
|
|
86
|
+
*
|
|
87
|
+
* Because it's easy to accidentally include unsuitable log context (e.g.
|
|
88
|
+
* redux state, PII) nested objects are not allowed. The restriction doesn't
|
|
89
|
+
* make it impossible, but it makes it harder to miss during code review.
|
|
90
|
+
*
|
|
91
|
+
* @example { userId: 123, reason: 'disconnect' }
|
|
92
|
+
*/
|
|
93
|
+
readonly context: LogContext;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* A more general type expected by logging backends. Supports type narrowing,
|
|
98
|
+
* so if a known field exists, it will be used instead of the generic JSON
|
|
99
|
+
* type.
|
|
100
|
+
*/
|
|
101
|
+
export declare type LogContext = Partial<CustomContext> & JsonContext;
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* This is the public API which generates and sends `Log` events through the
|
|
105
|
+
* user-defined processing pipeline.
|
|
106
|
+
*/
|
|
107
|
+
export declare interface Logger {
|
|
108
|
+
readonly owner: ReadonlyArray<string>;
|
|
109
|
+
/** Extend the logger to attach a class or module name to logs. */
|
|
110
|
+
namespace: (owner: string) => Logger;
|
|
111
|
+
/**
|
|
112
|
+
* Create a new logger which runs all logs through a middleware function.
|
|
113
|
+
* Useful for adding default context, doing ad-hoc filtering, or
|
|
114
|
+
* registering plugins. Only applies to this logger and its descendants.
|
|
115
|
+
*/
|
|
116
|
+
withMiddleware: (middleware: (next: LogProcessor) => LogProcessor) => Logger;
|
|
117
|
+
/** Log a verbose and frequent update. */
|
|
118
|
+
trace: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
|
|
119
|
+
/** Log a frequent and verbose progress update. */
|
|
120
|
+
debug: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
|
|
121
|
+
/** Log a high-level progress update. */
|
|
122
|
+
info: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
|
|
123
|
+
/** Log something concerning. */
|
|
124
|
+
warn: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
|
|
125
|
+
/** Log a failure. */
|
|
126
|
+
error: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
|
|
127
|
+
/** Log a catastrophic failure. */
|
|
128
|
+
fatal: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
export declare type LogLevel = (typeof level)[keyof typeof level];
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* A logger is made up of log processors. These processors take structured
|
|
135
|
+
* logs and do something with them. Examples are logging backends (console,
|
|
136
|
+
* file, uploads) and operators (filtering, transforming, aggregating).
|
|
137
|
+
*/
|
|
138
|
+
export declare interface LogProcessor {
|
|
139
|
+
/** Do something with a log message. */
|
|
140
|
+
(log: Log): unknown;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* A type narrowing constraint designed for generic constraints. Controls
|
|
145
|
+
* what fields are allowed in `log.context`, sourcing from `CustomContext`
|
|
146
|
+
* first, then falling back to any JSON value.
|
|
147
|
+
*/
|
|
148
|
+
declare type StrictContext<Input> = {
|
|
149
|
+
[Key in keyof Input]: Key extends keyof CustomContext ? CustomContext[Key] : JsonPrimitive | ReadonlyArray<JsonPrimitive>;
|
|
150
|
+
};
|
|
151
|
+
|
|
152
|
+
export { }
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@holz/core",
|
|
3
|
-
"version": "0.8.3-rc.
|
|
3
|
+
"version": "0.8.3-rc.156+23f99c0",
|
|
4
4
|
"description": "A structured and composable logger",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"repository": {
|
|
@@ -32,9 +32,11 @@
|
|
|
32
32
|
"scripts": {
|
|
33
33
|
"prepack": "vite build",
|
|
34
34
|
"test:unit": "vitest run --color --passWithNoTests",
|
|
35
|
+
"test:coverage": "vitest run --coverage --color --passWithNoTests",
|
|
35
36
|
"test:types": "tsc"
|
|
36
37
|
},
|
|
37
38
|
"devDependencies": {
|
|
39
|
+
"@microsoft/api-extractor": "^7.58.8",
|
|
38
40
|
"@vitest/coverage-v8": "^4.0.0",
|
|
39
41
|
"typescript": "^6.0.0",
|
|
40
42
|
"vite": "^8.0.0",
|
|
@@ -42,5 +44,5 @@
|
|
|
42
44
|
"vite-tsconfig-paths": "^6.0.0",
|
|
43
45
|
"vitest": "^4.0.0"
|
|
44
46
|
},
|
|
45
|
-
"gitHead": "
|
|
47
|
+
"gitHead": "23f99c04bcaa88f54e7b5d6b117e324de821a8d5"
|
|
46
48
|
}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|
package/dist/src/index.d.ts
DELETED
package/dist/src/logger.d.ts
DELETED
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
import { LogProcessor, Logger } from './types';
|
|
2
|
-
/**
|
|
3
|
-
* Create a new logger. The processor is up to you. There are plugins for
|
|
4
|
-
* filtering, formatting, combining multiple processors together, and more.
|
|
5
|
-
*
|
|
6
|
-
* If you wish to use more than one processor, `combine(...)` them first.
|
|
7
|
-
*/
|
|
8
|
-
export declare const createLogger: (processor: LogProcessor) => Logger;
|
package/dist/src/operators.d.ts
DELETED
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
import { Log, LogProcessor } from './types';
|
|
2
|
-
/**
|
|
3
|
-
* Combine several log processors into a single log processor. Each one is
|
|
4
|
-
* called in sequence. Useful for sending a single log to multiple log
|
|
5
|
-
* destinations.
|
|
6
|
-
*/
|
|
7
|
-
export declare const combine: (processors: Array<LogProcessor>) => LogProcessor;
|
|
8
|
-
/**
|
|
9
|
-
* Filter logs based on a filter function. If the function returns true, the
|
|
10
|
-
* log is kept and forwarded onto the next processor, otherwise it is
|
|
11
|
-
* discarded.
|
|
12
|
-
*/
|
|
13
|
-
export declare const filter: (
|
|
14
|
-
/** Returns `true` to forward the log. */
|
|
15
|
-
predicate: (log: Log) => boolean,
|
|
16
|
-
/** Where to send the log if it passes the filter. */
|
|
17
|
-
processor: LogProcessor) => LogProcessor;
|