@imqueue/async-logger 3.0.1 → 3.2.0
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/CONTRIBUTING.md +58 -0
- package/CONTRIBUTION-TERMS.md +79 -0
- package/SECURITY.md +41 -0
- package/index.d.ts +50 -2
- package/index.js +51 -20
- package/package.json +14 -4
- package/signatures/version1/cla.json +3 -0
- package/src/Logger.d.ts +96 -31
- package/src/Logger.js +118 -45
- package/src/TransportOptions.d.ts +36 -2
- package/src/TransportOptions.js +22 -2
- package/src/helpers/env.d.ts +31 -8
- package/src/helpers/env.js +60 -19
- package/src/helpers/index.d.ts +3 -3
- package/src/helpers/index.js +3 -19
- package/src/helpers/message.d.ts +9 -3
- package/src/helpers/message.js +12 -9
- package/src/helpers/transport.d.ts +12 -7
- package/src/helpers/transport.js +14 -12
- package/src/index.d.ts +4 -3
- package/src/index.js +4 -19
- package/src/types.d.ts +65 -0
- package/src/types.js +23 -0
package/src/Logger.js
CHANGED
|
@@ -1,16 +1,66 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
1
|
+
/*!
|
|
2
|
+
* I'm Queue Software Project
|
|
3
|
+
* Copyright (C) 2025 imqueue.com <support@imqueue.com>
|
|
4
|
+
*
|
|
5
|
+
* This program is free software: you can redistribute it and/or modify
|
|
6
|
+
* it under the terms of the GNU General Public License as published by
|
|
7
|
+
* the Free Software Foundation, either version 3 of the License, or
|
|
8
|
+
* (at your option) any later version.
|
|
9
|
+
*
|
|
10
|
+
* This program is distributed in the hope that it will be useful,
|
|
11
|
+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
12
|
+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
13
|
+
* GNU General Public License for more details.
|
|
14
|
+
*
|
|
15
|
+
* You should have received a copy of the GNU General Public License
|
|
16
|
+
* along with this program. If not, see <https://www.gnu.org/licenses/>.
|
|
17
|
+
*
|
|
18
|
+
* If you want to use this code in a closed source (commercial) project, you can
|
|
19
|
+
* purchase a proprietary commercial license. Please contact us at
|
|
20
|
+
* <support@imqueue.com> to get commercial licensing options.
|
|
21
|
+
*/
|
|
22
|
+
import {} from './types.js';
|
|
23
|
+
import { createLogger, format, Logger as WinstonLogger, } from 'winston';
|
|
24
|
+
import { buildMessage, defaultMetadata, getTransport, transportsConfig, } from './helpers/index.js';
|
|
25
|
+
import {} from './TransportOptions.js';
|
|
6
26
|
/**
|
|
7
|
-
*
|
|
27
|
+
* Logger that writes to the console without blocking the caller and forwards the
|
|
28
|
+
* same records to any configured winston transports.
|
|
29
|
+
*
|
|
30
|
+
* @remarks
|
|
31
|
+
* Implements {@link ILogger}, so it drops into anything in `@imqueue` that accepts
|
|
32
|
+
* a logger — `IMQClient`, `IMQService`, `RedisCache` — replacing the default
|
|
33
|
+
* synchronous console.
|
|
34
|
+
*
|
|
35
|
+
* Console output is scheduled with `setTimeout` rather than written inline. That
|
|
36
|
+
* is the point of the package: a service logging heavily does not pay for it on
|
|
37
|
+
* the request path. It also means ordering against synchronous code is not
|
|
38
|
+
* guaranteed, and output queued at the moment of `process.exit()` is lost.
|
|
39
|
+
*
|
|
40
|
+
* Transports are optional. Constructed with none — the default when
|
|
41
|
+
* `LOGGER_TRANSPORTS` is unset — this behaves as an async console logger and
|
|
42
|
+
* never touches winston.
|
|
43
|
+
*
|
|
44
|
+
* @example
|
|
45
|
+
* ```typescript
|
|
46
|
+
* import { Logger } from '@imqueue/async-logger';
|
|
47
|
+
*
|
|
48
|
+
* // configured from LOGGER_TRANSPORTS / LOGGER_METADATA
|
|
49
|
+
* const logger = new Logger();
|
|
50
|
+
*
|
|
51
|
+
* // or explicitly, e.g. to tag one subsystem differently
|
|
52
|
+
* const audit = new Logger({
|
|
53
|
+
* transports: [{ type: 'file', options: { filename: 'audit.log' }, enabled: true }],
|
|
54
|
+
* metadata: { subsystem: 'audit' },
|
|
55
|
+
* });
|
|
56
|
+
*
|
|
57
|
+
* audit.info('user %s signed in', userId);
|
|
58
|
+
* ```
|
|
8
59
|
*/
|
|
9
|
-
class Logger {
|
|
60
|
+
export class Logger {
|
|
10
61
|
/**
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
* @type {ILogger}
|
|
62
|
+
* Console bound through `setTimeout`, so every write is deferred to a later
|
|
63
|
+
* tick instead of blocking the caller.
|
|
14
64
|
*/
|
|
15
65
|
static console = {
|
|
16
66
|
// oxlint-disable-next-line no-console -- forwarding is the API here
|
|
@@ -20,91 +70,108 @@ class Logger {
|
|
|
20
70
|
error: (...args) => setTimeout(() => console.error(...args)),
|
|
21
71
|
};
|
|
22
72
|
/**
|
|
23
|
-
*
|
|
24
|
-
*
|
|
73
|
+
* Builds the winston options every transport shares: JSON formatting, the
|
|
74
|
+
* given (or environment-derived) default metadata, and `exitOnError: false`
|
|
75
|
+
* so a transport failure never takes the process down.
|
|
25
76
|
*
|
|
26
|
-
* @
|
|
77
|
+
* @param metadata - fields to attach to every record; falls back to
|
|
78
|
+
* `LOGGER_METADATA` when omitted
|
|
79
|
+
* @returns winston logger options
|
|
27
80
|
*/
|
|
28
81
|
static getLoggerOptions(metadata) {
|
|
29
82
|
return {
|
|
30
83
|
exitOnError: false,
|
|
31
|
-
format:
|
|
32
|
-
defaultMeta: metadata ||
|
|
84
|
+
format: format.json(),
|
|
85
|
+
defaultMeta: metadata || defaultMetadata(),
|
|
33
86
|
};
|
|
34
87
|
}
|
|
35
88
|
/**
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
89
|
+
* The winston logger the transports are attached to. Left undefined when no
|
|
90
|
+
* enabled transport was configured, which is how console-only mode is
|
|
91
|
+
* represented — every method checks it before forwarding.
|
|
39
92
|
*/
|
|
40
93
|
logger;
|
|
41
94
|
/**
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
* @
|
|
95
|
+
* @param options - explicit transports and metadata. Omit either half and it
|
|
96
|
+
* is read from `LOGGER_TRANSPORTS` / `LOGGER_METADATA`; omit
|
|
97
|
+
* the argument entirely and both are.
|
|
98
|
+
* @throws TypeError if the environment config is not valid JSON, or names a
|
|
99
|
+
* transport type other than `file` or `http`
|
|
46
100
|
*/
|
|
47
101
|
constructor(options) {
|
|
48
102
|
const opts = Logger.getLoggerOptions((options || {}).metadata);
|
|
49
|
-
const config = (options || {}).transports ||
|
|
103
|
+
const config = (options || {}).transports || transportsConfig();
|
|
50
104
|
if (config && config.length) {
|
|
51
|
-
this.logger =
|
|
105
|
+
this.logger = createLogger(opts);
|
|
52
106
|
this.setupLogger(config);
|
|
53
107
|
}
|
|
54
108
|
}
|
|
55
109
|
/**
|
|
56
|
-
* Logs
|
|
57
|
-
* with log level = LOG
|
|
110
|
+
* Logs to the console and to every configured transport.
|
|
58
111
|
*
|
|
59
|
-
* @
|
|
112
|
+
* @remarks
|
|
113
|
+
* Reaches transports at winston's `info` level — there is no distinct `log`
|
|
114
|
+
* level — so records from here and from {@link Logger.info} are
|
|
115
|
+
* indistinguishable once shipped. They differ only in the console method
|
|
116
|
+
* used. Pick by the destination you care about.
|
|
117
|
+
*
|
|
118
|
+
* @param args - `console.log`-style arguments; the first may be a format
|
|
119
|
+
* string with `%s`/`%d`/`%j` placeholders for the rest
|
|
60
120
|
*/
|
|
61
121
|
log(...args) {
|
|
62
122
|
Logger.console.log(...args);
|
|
63
123
|
if (this.logger) {
|
|
64
|
-
this.logger.info(
|
|
124
|
+
this.logger.info(buildMessage(args));
|
|
65
125
|
}
|
|
66
126
|
}
|
|
67
127
|
/**
|
|
68
|
-
* Logs
|
|
69
|
-
* with log level = INFO
|
|
128
|
+
* Logs at INFO level — routine progress worth keeping.
|
|
70
129
|
*
|
|
71
|
-
* @param
|
|
130
|
+
* @param args - `console.info`-style arguments; the first may be a format
|
|
131
|
+
* string with `%s`/`%d`/`%j` placeholders for the rest
|
|
72
132
|
*/
|
|
73
133
|
info(...args) {
|
|
74
134
|
Logger.console.info(...args);
|
|
75
135
|
if (this.logger) {
|
|
76
|
-
this.logger.info(
|
|
136
|
+
this.logger.info(buildMessage(args));
|
|
77
137
|
}
|
|
78
138
|
}
|
|
79
139
|
/**
|
|
80
|
-
* Logs
|
|
81
|
-
* with log level = WARN
|
|
140
|
+
* Logs at WARN level — something recovered from, but worth seeing.
|
|
82
141
|
*
|
|
83
|
-
* @param
|
|
142
|
+
* @param args - `console.warn`-style arguments; the first may be a format
|
|
143
|
+
* string with `%s`/`%d`/`%j` placeholders for the rest
|
|
84
144
|
*/
|
|
85
145
|
warn(...args) {
|
|
86
146
|
Logger.console.warn(...args);
|
|
87
147
|
if (this.logger) {
|
|
88
|
-
this.logger.warn(
|
|
148
|
+
this.logger.warn(buildMessage(args));
|
|
89
149
|
}
|
|
90
150
|
}
|
|
91
151
|
/**
|
|
92
|
-
* Logs
|
|
93
|
-
*
|
|
152
|
+
* Logs at ERROR level.
|
|
153
|
+
*
|
|
154
|
+
* @remarks
|
|
155
|
+
* Pass an `Error` and it is formatted like the console would — including the
|
|
156
|
+
* stack. Passing `error.stack` explicitly is the usual choice when the record
|
|
157
|
+
* has to stay one line for a log shipper.
|
|
94
158
|
*
|
|
95
|
-
* @param
|
|
159
|
+
* @param args - `console.error`-style arguments; the first may be a format
|
|
160
|
+
* string with `%s`/`%d`/`%j` placeholders for the rest
|
|
96
161
|
*/
|
|
97
162
|
error(...args) {
|
|
98
163
|
Logger.console.error(...args);
|
|
99
164
|
if (this.logger) {
|
|
100
|
-
this.logger.error(
|
|
165
|
+
this.logger.error(buildMessage(args));
|
|
101
166
|
}
|
|
102
167
|
}
|
|
103
168
|
/**
|
|
104
|
-
*
|
|
169
|
+
* Creates and attaches each enabled transport from the given config.
|
|
105
170
|
*
|
|
106
|
-
* @param
|
|
107
|
-
*
|
|
171
|
+
* @param config - transport definitions, from {@link AsyncLoggerOptions} or
|
|
172
|
+
* parsed out of `LOGGER_TRANSPORTS`
|
|
173
|
+
* @throws TypeError if `config` is not an array, or an enabled entry names a
|
|
174
|
+
* transport type other than `file` or `http`
|
|
108
175
|
*/
|
|
109
176
|
setupLogger(config) {
|
|
110
177
|
if (!config || !Array.isArray(config)) {
|
|
@@ -114,7 +181,14 @@ class Logger {
|
|
|
114
181
|
if (!options.enabled) {
|
|
115
182
|
continue;
|
|
116
183
|
}
|
|
117
|
-
const transport =
|
|
184
|
+
const transport = getTransport(options.type, options.options);
|
|
185
|
+
// getTransport() yields nothing for a type it does not know. Report
|
|
186
|
+
// the offending type here: winston would otherwise reject the null
|
|
187
|
+
// with "Invalid transport, must be an object with a log method",
|
|
188
|
+
// which names neither the type nor the config it came from.
|
|
189
|
+
if (!transport) {
|
|
190
|
+
throw new TypeError(`Logger: unknown transport type "${options.type}", expected "file" or "http"!`);
|
|
191
|
+
}
|
|
118
192
|
// the constructor always creates the winston logger before
|
|
119
193
|
// calling setupLogger(), the optional chaining only satisfies
|
|
120
194
|
// strict property-initialization analysis
|
|
@@ -122,5 +196,4 @@ class Logger {
|
|
|
122
196
|
}
|
|
123
197
|
}
|
|
124
198
|
}
|
|
125
|
-
exports.Logger = Logger;
|
|
126
199
|
//# sourceMappingURL=Logger.js.map
|
|
@@ -19,12 +19,46 @@
|
|
|
19
19
|
* purchase a proprietary commercial license. Please contact us at
|
|
20
20
|
* <support@imqueue.com> to get commercial licensing options.
|
|
21
21
|
*/
|
|
22
|
-
import { LoggerOptions } from 'winston';
|
|
22
|
+
import { type LoggerOptions } from 'winston';
|
|
23
23
|
/**
|
|
24
|
-
*
|
|
24
|
+
* One transport declaration — the shape of each element in the
|
|
25
|
+
* `LOGGER_TRANSPORTS` JSON array.
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
* ```json
|
|
29
|
+
* {
|
|
30
|
+
* "type": "http",
|
|
31
|
+
* "options": {
|
|
32
|
+
* "ssl": true,
|
|
33
|
+
* "port": 443,
|
|
34
|
+
* "host": "http-intake.logs.datadoghq.com",
|
|
35
|
+
* "path": "/v1/input/<API_KEY>"
|
|
36
|
+
* },
|
|
37
|
+
* "enabled": true
|
|
38
|
+
* }
|
|
39
|
+
* ```
|
|
25
40
|
*/
|
|
26
41
|
export interface TransportOptions {
|
|
42
|
+
/**
|
|
43
|
+
* Which transport to create: `'file'` or `'http'`. Any other value is
|
|
44
|
+
* rejected at construction time.
|
|
45
|
+
*/
|
|
27
46
|
type: string;
|
|
47
|
+
/**
|
|
48
|
+
* Options handed to the winston transport constructor — `filename` for
|
|
49
|
+
* `file`, `host`/`port`/`path`/`ssl` for `http`.
|
|
50
|
+
*
|
|
51
|
+
* @remarks
|
|
52
|
+
* Typed as winston's `LoggerOptions` for historical reasons, which is wider
|
|
53
|
+
* than what is actually accepted here. Treat it as `FileTransportOptions` or
|
|
54
|
+
* `HttpTransportOptions` according to `type`; the declared type will not
|
|
55
|
+
* catch a mismatch for you.
|
|
56
|
+
*/
|
|
28
57
|
options: LoggerOptions;
|
|
58
|
+
/**
|
|
59
|
+
* Whether to attach this transport. A `false` entry is skipped entirely, so
|
|
60
|
+
* a transport can be left in the config and switched off per environment
|
|
61
|
+
* rather than deleted.
|
|
62
|
+
*/
|
|
29
63
|
enabled: boolean;
|
|
30
64
|
}
|
package/src/TransportOptions.js
CHANGED
|
@@ -1,3 +1,23 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
/*!
|
|
2
|
+
* I'm Queue Software Project
|
|
3
|
+
* Copyright (C) 2025 imqueue.com <support@imqueue.com>
|
|
4
|
+
*
|
|
5
|
+
* This program is free software: you can redistribute it and/or modify
|
|
6
|
+
* it under the terms of the GNU General Public License as published by
|
|
7
|
+
* the Free Software Foundation, either version 3 of the License, or
|
|
8
|
+
* (at your option) any later version.
|
|
9
|
+
*
|
|
10
|
+
* This program is distributed in the hope that it will be useful,
|
|
11
|
+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
12
|
+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
13
|
+
* GNU General Public License for more details.
|
|
14
|
+
*
|
|
15
|
+
* You should have received a copy of the GNU General Public License
|
|
16
|
+
* along with this program. If not, see <https://www.gnu.org/licenses/>.
|
|
17
|
+
*
|
|
18
|
+
* If you want to use this code in a closed source (commercial) project, you can
|
|
19
|
+
* purchase a proprietary commercial license. Please contact us at
|
|
20
|
+
* <support@imqueue.com> to get commercial licensing options.
|
|
21
|
+
*/
|
|
22
|
+
import {} from 'winston';
|
|
3
23
|
//# sourceMappingURL=TransportOptions.js.map
|
package/src/helpers/env.d.ts
CHANGED
|
@@ -19,26 +19,49 @@
|
|
|
19
19
|
* purchase a proprietary commercial license. Please contact us at
|
|
20
20
|
* <support@imqueue.com> to get commercial licensing options.
|
|
21
21
|
*/
|
|
22
|
-
import { JsonObject } from '
|
|
23
|
-
import { TransportOptions } from '../TransportOptions';
|
|
22
|
+
import { type JsonObject } from '../types.js';
|
|
23
|
+
import { type TransportOptions } from '../TransportOptions.js';
|
|
24
24
|
/**
|
|
25
|
-
*
|
|
25
|
+
* Reads the running service's own name and version, used to expand the `%name`
|
|
26
|
+
* and `%version` placeholders in the logger environment variables.
|
|
26
27
|
*
|
|
27
|
-
* @
|
|
28
|
+
* @remarks
|
|
29
|
+
* Resolved from `package.json` in the process's CURRENT WORKING DIRECTORY, not
|
|
30
|
+
* from this package's location. A service started from a different directory
|
|
31
|
+
* therefore reports whatever it finds there, and one started somewhere with no
|
|
32
|
+
* `package.json` falls back to `{ name: 'logger', version: '' }` rather than
|
|
33
|
+
* failing.
|
|
34
|
+
*
|
|
35
|
+
* @returns the service name and version, or the fallback pair
|
|
28
36
|
*/
|
|
29
37
|
export declare function pkg(): {
|
|
30
38
|
name: string;
|
|
31
39
|
version: string;
|
|
32
40
|
};
|
|
33
41
|
/**
|
|
34
|
-
*
|
|
42
|
+
* Parses the transport declarations out of `LOGGER_TRANSPORTS`, expanding
|
|
43
|
+
* `%name` and `%version` first.
|
|
44
|
+
*
|
|
45
|
+
* @remarks
|
|
46
|
+
* An unset variable yields an empty array, which the {@link Logger} treats as
|
|
47
|
+
* console-only rather than as an error — the normal local-development case.
|
|
48
|
+
* Malformed JSON, by contrast, throws: a config typo should fail loudly at
|
|
49
|
+
* start-up rather than silently drop a production log destination.
|
|
35
50
|
*
|
|
36
|
-
* @returns
|
|
51
|
+
* @returns the declared transports, or an empty array when unset
|
|
52
|
+
* @throws TypeError if the variable is set but not parseable as JSON
|
|
37
53
|
*/
|
|
38
54
|
export declare function transportsConfig(): TransportOptions[];
|
|
39
55
|
/**
|
|
40
|
-
*
|
|
56
|
+
* Parses the default record metadata out of `LOGGER_METADATA`, expanding `%name`
|
|
57
|
+
* and `%version` first.
|
|
58
|
+
*
|
|
59
|
+
* @remarks
|
|
60
|
+
* These fields are attached to every record sent to a transport — a source tag,
|
|
61
|
+
* an environment name, a hostname — and are what makes records from several
|
|
62
|
+
* services distinguishable at the collector. Console output is unaffected.
|
|
41
63
|
*
|
|
42
|
-
* @returns
|
|
64
|
+
* @returns the parsed metadata, or an empty object when unset
|
|
65
|
+
* @throws TypeError if the variable is set but not parseable as JSON
|
|
43
66
|
*/
|
|
44
67
|
export declare function defaultMetadata(): JsonObject;
|
package/src/helpers/env.js
CHANGED
|
@@ -1,30 +1,64 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
1
|
+
/*!
|
|
2
|
+
* I'm Queue Software Project
|
|
3
|
+
* Copyright (C) 2025 imqueue.com <support@imqueue.com>
|
|
4
|
+
*
|
|
5
|
+
* This program is free software: you can redistribute it and/or modify
|
|
6
|
+
* it under the terms of the GNU General Public License as published by
|
|
7
|
+
* the Free Software Foundation, either version 3 of the License, or
|
|
8
|
+
* (at your option) any later version.
|
|
9
|
+
*
|
|
10
|
+
* This program is distributed in the hope that it will be useful,
|
|
11
|
+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
12
|
+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
13
|
+
* GNU General Public License for more details.
|
|
14
|
+
*
|
|
15
|
+
* You should have received a copy of the GNU General Public License
|
|
16
|
+
* along with this program. If not, see <https://www.gnu.org/licenses/>.
|
|
17
|
+
*
|
|
18
|
+
* If you want to use this code in a closed source (commercial) project, you can
|
|
19
|
+
* purchase a proprietary commercial license. Please contact us at
|
|
20
|
+
* <support@imqueue.com> to get commercial licensing options.
|
|
21
|
+
*/
|
|
22
|
+
import {} from '../types.js';
|
|
23
|
+
import { resolve } from 'path';
|
|
24
|
+
import { existsSync as exists, readFileSync } from 'fs';
|
|
25
|
+
import {} from '../TransportOptions.js';
|
|
8
26
|
const RX_NAME = /%name/g;
|
|
9
27
|
const RX_VERSION = /%version/g;
|
|
10
28
|
/**
|
|
11
|
-
*
|
|
29
|
+
* Reads the running service's own name and version, used to expand the `%name`
|
|
30
|
+
* and `%version` placeholders in the logger environment variables.
|
|
31
|
+
*
|
|
32
|
+
* @remarks
|
|
33
|
+
* Resolved from `package.json` in the process's CURRENT WORKING DIRECTORY, not
|
|
34
|
+
* from this package's location. A service started from a different directory
|
|
35
|
+
* therefore reports whatever it finds there, and one started somewhere with no
|
|
36
|
+
* `package.json` falls back to `{ name: 'logger', version: '' }` rather than
|
|
37
|
+
* failing.
|
|
12
38
|
*
|
|
13
|
-
* @returns
|
|
39
|
+
* @returns the service name and version, or the fallback pair
|
|
14
40
|
*/
|
|
15
|
-
function pkg() {
|
|
16
|
-
const pkgPath =
|
|
17
|
-
const { name, version } = (
|
|
18
|
-
?
|
|
41
|
+
export function pkg() {
|
|
42
|
+
const pkgPath = resolve(process.cwd(), 'package.json');
|
|
43
|
+
const { name, version } = exists(pkgPath)
|
|
44
|
+
? JSON.parse(readFileSync(pkgPath, 'utf8'))
|
|
19
45
|
: { name: 'logger', version: '' };
|
|
20
46
|
return { name, version };
|
|
21
47
|
}
|
|
22
48
|
/**
|
|
23
|
-
*
|
|
49
|
+
* Parses the transport declarations out of `LOGGER_TRANSPORTS`, expanding
|
|
50
|
+
* `%name` and `%version` first.
|
|
24
51
|
*
|
|
25
|
-
* @
|
|
52
|
+
* @remarks
|
|
53
|
+
* An unset variable yields an empty array, which the {@link Logger} treats as
|
|
54
|
+
* console-only rather than as an error — the normal local-development case.
|
|
55
|
+
* Malformed JSON, by contrast, throws: a config typo should fail loudly at
|
|
56
|
+
* start-up rather than silently drop a production log destination.
|
|
57
|
+
*
|
|
58
|
+
* @returns the declared transports, or an empty array when unset
|
|
59
|
+
* @throws TypeError if the variable is set but not parseable as JSON
|
|
26
60
|
*/
|
|
27
|
-
function transportsConfig() {
|
|
61
|
+
export function transportsConfig() {
|
|
28
62
|
const { name, version } = pkg();
|
|
29
63
|
try {
|
|
30
64
|
return JSON.parse((process.env.LOGGER_TRANSPORTS || '[]')
|
|
@@ -36,11 +70,18 @@ function transportsConfig() {
|
|
|
36
70
|
}
|
|
37
71
|
}
|
|
38
72
|
/**
|
|
39
|
-
*
|
|
73
|
+
* Parses the default record metadata out of `LOGGER_METADATA`, expanding `%name`
|
|
74
|
+
* and `%version` first.
|
|
75
|
+
*
|
|
76
|
+
* @remarks
|
|
77
|
+
* These fields are attached to every record sent to a transport — a source tag,
|
|
78
|
+
* an environment name, a hostname — and are what makes records from several
|
|
79
|
+
* services distinguishable at the collector. Console output is unaffected.
|
|
40
80
|
*
|
|
41
|
-
* @returns
|
|
81
|
+
* @returns the parsed metadata, or an empty object when unset
|
|
82
|
+
* @throws TypeError if the variable is set but not parseable as JSON
|
|
42
83
|
*/
|
|
43
|
-
function defaultMetadata() {
|
|
84
|
+
export function defaultMetadata() {
|
|
44
85
|
const { name, version } = pkg();
|
|
45
86
|
try {
|
|
46
87
|
return JSON.parse((process.env.LOGGER_METADATA || '{}')
|
package/src/helpers/index.d.ts
CHANGED
|
@@ -19,6 +19,6 @@
|
|
|
19
19
|
* purchase a proprietary commercial license. Please contact us at
|
|
20
20
|
* <support@imqueue.com> to get commercial licensing options.
|
|
21
21
|
*/
|
|
22
|
-
export * from './env';
|
|
23
|
-
export * from './message';
|
|
24
|
-
export * from './transport';
|
|
22
|
+
export * from './env.js';
|
|
23
|
+
export * from './message.js';
|
|
24
|
+
export * from './transport.js';
|
package/src/helpers/index.js
CHANGED
|
@@ -1,19 +1,3 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
-
if (k2 === undefined) k2 = k;
|
|
4
|
-
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
-
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
-
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
-
}
|
|
8
|
-
Object.defineProperty(o, k2, desc);
|
|
9
|
-
}) : (function(o, m, k, k2) {
|
|
10
|
-
if (k2 === undefined) k2 = k;
|
|
11
|
-
o[k2] = m[k];
|
|
12
|
-
}));
|
|
13
|
-
var __exportStar = (this && this.__exportStar) || function(m, exports) {
|
|
14
|
-
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
|
15
|
-
};
|
|
16
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
17
1
|
/*!
|
|
18
2
|
* I'm Queue Software Project
|
|
19
3
|
* Copyright (C) 2025 imqueue.com <support@imqueue.com>
|
|
@@ -35,7 +19,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
35
19
|
* purchase a proprietary commercial license. Please contact us at
|
|
36
20
|
* <support@imqueue.com> to get commercial licensing options.
|
|
37
21
|
*/
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
22
|
+
export * from './env.js';
|
|
23
|
+
export * from './message.js';
|
|
24
|
+
export * from './transport.js';
|
|
41
25
|
//# sourceMappingURL=index.js.map
|
package/src/helpers/message.d.ts
CHANGED
|
@@ -1,7 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Renders `console.log`-style arguments into the single string a transport
|
|
3
|
+
* record needs, applying `util.format` so `%s`/`%d`/`%j` placeholders and object
|
|
4
|
+
* inspection behave exactly as they do on the console.
|
|
3
5
|
*
|
|
4
|
-
* @
|
|
5
|
-
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* MUTATES the array it is given — the first element is shifted off to serve as
|
|
8
|
+
* the format string. Pass a copy if you need the original afterwards.
|
|
9
|
+
*
|
|
10
|
+
* @param args - the logging arguments, first one treated as the format string
|
|
11
|
+
* @returns the formatted message
|
|
6
12
|
*/
|
|
7
13
|
export declare function buildMessage(args: any[]): string;
|
package/src/helpers/message.js
CHANGED
|
@@ -1,6 +1,3 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.buildMessage = buildMessage;
|
|
4
1
|
/*!
|
|
5
2
|
* I'm Queue Software Project
|
|
6
3
|
* Copyright (C) 2025 imqueue.com <support@imqueue.com>
|
|
@@ -22,14 +19,20 @@ exports.buildMessage = buildMessage;
|
|
|
22
19
|
* purchase a proprietary commercial license. Please contact us at
|
|
23
20
|
* <support@imqueue.com> to get commercial licensing options.
|
|
24
21
|
*/
|
|
25
|
-
|
|
22
|
+
import { format } from 'util';
|
|
26
23
|
/**
|
|
27
|
-
*
|
|
24
|
+
* Renders `console.log`-style arguments into the single string a transport
|
|
25
|
+
* record needs, applying `util.format` so `%s`/`%d`/`%j` placeholders and object
|
|
26
|
+
* inspection behave exactly as they do on the console.
|
|
28
27
|
*
|
|
29
|
-
* @
|
|
30
|
-
*
|
|
28
|
+
* @remarks
|
|
29
|
+
* MUTATES the array it is given — the first element is shifted off to serve as
|
|
30
|
+
* the format string. Pass a copy if you need the original afterwards.
|
|
31
|
+
*
|
|
32
|
+
* @param args - the logging arguments, first one treated as the format string
|
|
33
|
+
* @returns the formatted message
|
|
31
34
|
*/
|
|
32
|
-
function buildMessage(args) {
|
|
33
|
-
return
|
|
35
|
+
export function buildMessage(args) {
|
|
36
|
+
return format(args.shift(), ...args);
|
|
34
37
|
}
|
|
35
38
|
//# sourceMappingURL=message.js.map
|
|
@@ -1,11 +1,16 @@
|
|
|
1
|
-
import
|
|
2
|
-
import { FileTransportOptions, HttpTransportOptions } from 'winston/lib/winston/transports';
|
|
1
|
+
import type Transport from 'winston-transport';
|
|
2
|
+
import type { FileTransportOptions, HttpTransportOptions } from 'winston/lib/winston/transports/index.js';
|
|
3
3
|
/**
|
|
4
|
-
*
|
|
4
|
+
* Constructs a winston transport of the named type.
|
|
5
5
|
*
|
|
6
|
-
* @
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* @
|
|
6
|
+
* @remarks
|
|
7
|
+
* Only `'file'` and `'http'` are supported. Anything else returns nothing —
|
|
8
|
+
* despite the declared return type, which is a `Transport` cast rather than a
|
|
9
|
+
* guarantee. {@link Logger} checks for that and reports the offending type; a
|
|
10
|
+
* direct caller must check too.
|
|
11
|
+
*
|
|
12
|
+
* @param type - `'file'` or `'http'`
|
|
13
|
+
* @param options - options for the winston transport constructor
|
|
14
|
+
* @returns the transport, or nothing if the type is not recognised
|
|
10
15
|
*/
|
|
11
16
|
export declare function getTransport(type: string, options: FileTransportOptions | HttpTransportOptions): Transport;
|
package/src/helpers/transport.js
CHANGED
|
@@ -1,6 +1,3 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.getTransport = getTransport;
|
|
4
1
|
/*!
|
|
5
2
|
* I'm Queue Software Project
|
|
6
3
|
* Copyright (C) 2025 imqueue.com <support@imqueue.com>
|
|
@@ -22,22 +19,27 @@ exports.getTransport = getTransport;
|
|
|
22
19
|
* purchase a proprietary commercial license. Please contact us at
|
|
23
20
|
* <support@imqueue.com> to get commercial licensing options.
|
|
24
21
|
*/
|
|
25
|
-
|
|
22
|
+
import { transports } from 'winston';
|
|
26
23
|
/**
|
|
27
|
-
*
|
|
24
|
+
* Constructs a winston transport of the named type.
|
|
28
25
|
*
|
|
29
|
-
* @
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
* @
|
|
26
|
+
* @remarks
|
|
27
|
+
* Only `'file'` and `'http'` are supported. Anything else returns nothing —
|
|
28
|
+
* despite the declared return type, which is a `Transport` cast rather than a
|
|
29
|
+
* guarantee. {@link Logger} checks for that and reports the offending type; a
|
|
30
|
+
* direct caller must check too.
|
|
31
|
+
*
|
|
32
|
+
* @param type - `'file'` or `'http'`
|
|
33
|
+
* @param options - options for the winston transport constructor
|
|
34
|
+
* @returns the transport, or nothing if the type is not recognised
|
|
33
35
|
*/
|
|
34
|
-
function getTransport(type, options) {
|
|
36
|
+
export function getTransport(type, options) {
|
|
35
37
|
let transportInstance = null;
|
|
36
38
|
if (type === 'file') {
|
|
37
|
-
transportInstance = new
|
|
39
|
+
transportInstance = new transports.File(options);
|
|
38
40
|
}
|
|
39
41
|
else if (type === 'http') {
|
|
40
|
-
transportInstance = new
|
|
42
|
+
transportInstance = new transports.Http(options);
|
|
41
43
|
}
|
|
42
44
|
return transportInstance;
|
|
43
45
|
}
|
package/src/index.d.ts
CHANGED
|
@@ -19,6 +19,7 @@
|
|
|
19
19
|
* purchase a proprietary commercial license. Please contact us at
|
|
20
20
|
* <support@imqueue.com> to get commercial licensing options.
|
|
21
21
|
*/
|
|
22
|
-
export * from './
|
|
23
|
-
export * from './
|
|
24
|
-
export * from './
|
|
22
|
+
export * from './types.js';
|
|
23
|
+
export * from './helpers/index.js';
|
|
24
|
+
export * from './TransportOptions.js';
|
|
25
|
+
export * from './Logger.js';
|