Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 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 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 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 | 69x 1631x 1631x 8155x 1631x 1631x 1631x 1631x 1631x 944x 202x 698x 698x 698x 698x 76x 4653x 4653x 4653x 8809x 69x | /**
* A Logger is a logging facility that supports multiple transports and tags.
* The transports are the actual logging functions, and the tags are used to
* identify the source of the log message independent of its location in the
* code.
*
* @example
* ```ts
* const logger = new Logger('my-logger');
* logger.info('Hello, world!');
* >>> [my-logger] Hello, world!
* ```
*
* Sub-loggers can be created by calling the `subLogger` method. They inherit
* the tags and transports of their parent logger, and can add additional tags
* to their own messages.
*
*
* @example
* ```ts
* const subLogger = logger.subLogger('sub');
* subLogger.info('Hello, world!');
* >>> [my-logger, sub] Hello, world!
* ```
*
* The transports can be configured to ignore certain log levels, or to write
* different tags to different destinations, and so on. The default transports
* write to the console, but other transports can be added by passing a custom
* transport function to the constructor. The transports must be synchronous,
* but they can initiate asynchronous operations if needed.
*
* @example
* ```ts
* const logger = new Logger({
* tags: ['my-logger'],
* transports: [
* (entry) => {
* if (entry.tags.includes('vat')) {
* fs.writeFile('vat.log', `${entry.message}\n`, { flag: 'a' }).catch(
* (error) => {
* console.error('Error writing to vat.log:', error);
* },
* );
* }
* },
* ],
* });
* ```
*/
import type { DuplexStream } from '@metamask/streams';
import { parseOptions, mergeOptions } from './options.ts';
import { lunser } from './stream.ts';
import type { LogMessage } from './stream.ts';
import type {
LogLevel,
LogEntry,
LoggerOptions,
LogMethod,
LogArgs,
} from './types.ts';
// We make use of harden() if it exists, but we don't want to fail if it doesn't.
const harden = globalThis.harden ?? ((value: unknown) => value);
/**
* The logger class.
*/
export class Logger {
readonly #options: LoggerOptions;
/**
* Logs a message at the 'log' level.
*
* @param message - The message to log.
* @param args - Additional arguments to include in the log entry.
*/
log: LogMethod;
/**
* Logs a message at the 'debug' level.
*
* @param message - The message to log.
* @param args - Additional arguments to include in the log entry.
*/
debug: LogMethod;
/**
* Logs a message at the 'info' level.
*
* @param message - The message to log.
* @param args - Additional arguments to include in the log entry.
*/
info: LogMethod;
/**
* Logs a message at the 'warn' level.
*
* @param message - The message to log.
* @param args - Additional arguments to include in the log entry.
*/
warn: LogMethod;
/**
* Logs a message at the 'error' level.
*
* @param message - The message to log.
* @param args - Additional arguments to include in the log entry.
*/
error: LogMethod;
/**
* The constructor for the logger. Sub-loggers can be created by calling the
* `subLogger` method. Sub-loggers inherit the transports and tags of their
* parent logger.
*
* @param options - The options for the logger, or a string to use as the
* logger's tag.
* @param options.transports - The transports, which deliver the log messages
* to the appropriate destination.
* @param options.tags - The tags for the logger, which are accumulated by
* sub-loggers and passed to the transports.
*/
constructor(options: LoggerOptions | string | undefined = undefined) {
this.#options = parseOptions(options);
// Create aliases for the log methods, allowing them to be used in a
// manner similar to the console object.
const bind = (level: LogLevel): LogMethod => {
return harden(
this.#dispatch.bind(this, { ...this.#options }, level),
) as LogMethod;
};
this.debug = bind('debug');
this.info = bind('info');
this.log = bind('log');
this.warn = bind('warn');
this.error = bind('error');
}
/**
* Creates a sub-logger with the given options.
*
* @param options - The options for the sub-logger, or a string to use as the
* sub-logger's tag.
* @returns The sub-logger.
*/
subLogger(options: LoggerOptions | string = {}): Logger {
return new Logger(
mergeOptions(
this.#options,
typeof options === 'string' ? { tags: [options] } : options,
),
);
}
/**
* Injects a stream of log messages into the logger.
*
* @param stream - The stream of log messages to inject.
* @param onError - The function to call if an error occurs while draining
* the stream. If not provided, the error will be lost to the void.
*/
injectStream(
stream: DuplexStream<LogMessage>,
onError?: (error: unknown) => void,
): void {
stream
.drain(async ({ params }) => {
const [, args]: ['logger', string] = params;
const { level, tags, message, data } = lunser(args);
const logArgs: LogArgs =
message === undefined ? [] : [message, ...(data ?? [])];
this.#dispatch({ tags }, level, ...logArgs);
})
.catch((problem) => onError?.(problem));
}
/**
* Dispatches a log entry to all configured transports.
*
* @param options - Additional logger options to merge with the instance options.
* @param level - The severity level of the log entry.
* @param args - The message and additional data to include in the log entry.
*/
#dispatch(options: LoggerOptions, level: LogLevel, ...args: LogArgs): void {
const { transports, tags } = mergeOptions(this.#options, options);
const [message, ...data] = args;
const entry: LogEntry = harden({ level, tags, message, data });
transports.forEach((transport) => transport(entry));
}
}
harden(Logger);
|