diff --git a/types/pino/index.d.ts b/types/pino/index.d.ts index 697894089a..3af323a6ad 100644 --- a/types/pino/index.d.ts +++ b/types/pino/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for pino 5.14 +// Type definitions for pino 5.15 // Project: https://github.com/pinojs/pino.git, http://getpino.io // Definitions by: Peter Snider // BendingBender @@ -9,6 +9,7 @@ // Harris Lummis // Raoul Jaeckel // Cory Donkin +// Adam Vigneaux // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.7 @@ -266,30 +267,152 @@ declare namespace P { */ enabled?: boolean; /** - * Browser only, see http://getpino.io/#/?id=pino-in-the-browser. + * Browser only, see http://getpino.io/#/docs/browser. */ browser?: { /** - * This option will create a pino-like log object instead of passing all arguments to a console method. - * When `write` is set, `asObject` will always be `true`. + * The `asObject` option will create a pino-like log object instead of passing all arguments to a console + * method. When `write` is set, `asObject` will always be true. + * + * @example + * pino.info('hi') // creates and logs {msg: 'hi', level: 30, time: } */ asObject?: boolean; /** - * Instead of passing log messages to console.log they can be passed to a supplied function. If `write` is - * set to a single function, all logging objects are passed to this function. If write is an object, it can - * have methods that correspond to the levels. When a message is logged at a given level, the corresponding - * method is called. If a method isn't present, the logging falls back to using the `console`. + * Instead of passing log messages to `console.log` they can be passed to a supplied function. If `write` is + * set to a single function, all logging objects are passed to this function. If `write` is an object, it + * can have methods that correspond to the levels. When a message is logged at a given level, the + * corresponding method is called. If a method isn't present, the logging falls back to using the `console`. + * + * @example + * const pino = require('pino')({ + * browser: { + * write: (o) => { + * // do something with o + * } + * } + * }) + * + * @example + * const pino = require('pino')({ + * browser: { + * write: { + * info: function (o) { + * //process info log object + * }, + * error: function (o) { + * //process error log object + * } + * } + * } + * }) */ write?: | WriteFn | ({ - fatal?: WriteFn; - error?: WriteFn; - warn?: WriteFn; - info?: WriteFn; - debug?: WriteFn; - trace?: WriteFn; - } & { [logLevel: string]: WriteFn }); + fatal?: WriteFn; + error?: WriteFn; + warn?: WriteFn; + info?: WriteFn; + debug?: WriteFn; + trace?: WriteFn; + } & { [logLevel: string]: WriteFn }); + + /** + * The serializers provided to `pino` are ignored by default in the browser, including the standard + * serializers provided with Pino. Since the default destination for log messages is the console, values + * such as `Error` objects are enhanced for inspection, which they otherwise wouldn't be if the Error + * serializer was enabled. We can turn all serializers on or we can selectively enable them via an array. + * + * When `serialize` is `true` the standard error serializer is also enabled (see + * {@link https://github.com/pinojs/pino/blob/master/docs/api.md#pino-stdserializers}). This is a global + * serializer which will apply to any `Error` objects passed to the logger methods. + * + * If `serialize` is an array the standard error serializer is also automatically enabled, it can be + * explicitly disabled by including a string in the serialize array: `!stdSerializers.err` (see example). + * + * The `serialize` array also applies to any child logger serializers (see + * {@link https://github.com/pinojs/pino/blob/master/docs/api.md#bindingsserializers-object} for how to + * set child-bound serializers). + * + * Unlike server pino the serializers apply to every object passed to the logger method, if the `asObject` + * option is `true`, this results in the serializers applying to the first object (as in server pino). + * + * For more info on serializers see + * {@link https://github.com/pinojs/pino/blob/master/docs/api.md#serializers-object}. + * + * @example + * const pino = require('pino')({ + * browser: { + * serialize: true + * } + * }) + * + * @example + * const pino = require('pino')({ + * serializers: { + * custom: myCustomSerializer, + * another: anotherSerializer + * }, + * browser: { + * serialize: ['custom'] + * } + * }) + * // following will apply myCustomSerializer to the custom property, + * // but will not apply anotherSerializer to another key + * pino.info({custom: 'a', another: 'b'}) + * + * @example + * const pino = require('pino')({ + * serializers: { + * custom: myCustomSerializer, + * another: anotherSerializer + * }, + * browser: { + * serialize: ['!stdSerializers.err', 'custom'] //will not serialize Errors, will serialize `custom` keys + * } + * }) + */ + serialize?: boolean | string[]; + + /** + * Options for transmission of logs. + * + * @example + * const pino = require('pino')({ + * browser: { + * transmit: { + * level: 'warn', + * send: function (level, logEvent) { + * if (level === 'warn') { + * // maybe send the logEvent to a separate endpoint + * // or maybe analyse the messages further before sending + * } + * // we could also use the `logEvent.level.value` property to determine + * // numerical value + * if (logEvent.level.value >= 50) { // covers error and fatal + * + * // send the logEvent somewhere + * } + * } + * } + * } + * }) + */ + transmit?: { + /** + * Specifies the minimum level (inclusive) of when the `send` function should be called, if not supplied + * the `send` function will be called based on the main logging `level` (set via `options.level`, + * defaulting to `info`). + */ + level?: Level|string; + /** + * Remotely record log messages. + * + * @description Called after writing the log message. + */ + send: (level: Level, logEvent: LogEvent) => void; + } }; /** * key-value object added as child logger to each log line. If set to null the base child logger is not added @@ -366,6 +489,42 @@ declare namespace P { [key: string]: any; } + /** + * A data structure representing a log message, it represents the arguments passed to a logger statement, the level + * at which they were logged and the hierarchy of child bindings. + * + * @description By default serializers are not applied to log output in the browser, but they will always be applied + * to `messages` and `bindings` in the `logEvent` object. This allows us to ensure a consistent format for all + * values between server and client. + */ + interface LogEvent { + /** + * Unix epoch timestamp in milliseconds, the time is taken from the moment the logger method is called. + */ + ts: number; + /** + * All arguments passed to logger method, (for instance `logger.info('a', 'b', 'c')` would result in `messages` + * array `['a', 'b', 'c']`). + */ + messages: any[]; + /** + * Represents each child logger (if any), and the relevant bindings. + * + * @description For instance, given `logger.child({a: 1}).child({b: 2}).info({c: 3})`, the bindings array would + * hold `[{a: 1}, {b: 2}]` and the `messages` array would be `[{c: 3}]`. The `bindings` are ordered according to + * their position in the child logger hierarchy, with the lowest index being the top of the hierarchy. + */ + bindings: Bindings[]; + /** + * Holds the `label` (for instance `info`), and the corresponding numerical `value` (for instance `30`). + * This could be important in cases where client side level values and labels differ from server side. + */ + level: { + label: string; + value: number; + }; + } + type Logger = BaseLogger & { [key: string]: LogFn }; interface BaseLogger extends EventEmitter { diff --git a/types/pino/pino-tests.ts b/types/pino/pino-tests.ts index 61aa044c93..4e3bc92225 100644 --- a/types/pino/pino-tests.ts +++ b/types/pino/pino-tests.ts @@ -51,6 +51,18 @@ pino({ }, error(o) { } + }, + serialize: true, + asObject: true, + transmit: { + level: 'fatal', + send: (level, logEvent) => { + level; + logEvent.bindings; + logEvent.level; + logEvent.ts; + logEvent.messages; + } } } });