@rsdk/logging 5.12.0 → 5.13.0-next.0

package/dist/logger.factory.d.ts

@@ -6,7 +6,7 @@ import type { LoggerOptions, LoggingContext, OnMessage } from './types';
  */
 export declare class LoggerFactory {
     private static readonly events;
-    private static readonly opts;
+    private static opts;
     private static pinoTimestampFormatMap;
     /**
      * Under the hood every logger instance will use this
@@ -19,7 +19,10 @@ export declare class LoggerFactory {
      */
     private static _globalPino;
     private static _serializers;
-    private static get pinoConfig();
+    /** Ссылка на активный worker-транспорт для закрытия его воркеров. */
+    private static _activeTransport;
+    /** Конфиг, по которому собран _activeTransport (для переиспользования воркера). */
+    private static _activeTransportConfig;
     /**
      * Переконфигурация pino нужна потому, что изначально логгер инициализируется
      * с дефолтными настройками, т. к. конфигурация ещё не прочитана.
@@ -44,6 +47,11 @@ export declare class LoggerFactory {
      * при помощи cli - можно немного упростить архитектуру
      */
     static applyInstrumentations<T extends Record<string, any>>(logHookFunction?: (record: T) => void): void;
+    /**
+     * Сливает буфер worker-транспорта и завершает его воркеры. Без вызова на
+     * остановке приложения забуференные логи теряются, а воркеры висят.
+     */
+    static shutdown(timeoutMs?: number): Promise<void>;
     static onMessage(handler: OnMessage): void;
     static create(context: LoggingContext): ILogger;
     static getSerializers(): LogSerializerBase[];
@@ -66,4 +74,31 @@ export declare class LoggerFactory {
      */
     static hasSerializer(name: string): boolean;
     private static applyOptions;
+    /**
+     * `stream`/`transport` исключаем из опций: способ доставки задаётся вторым
+     * аргументом `pino()`, а pino запрещает одновременно `transport` в опциях и
+     * stream-аргумент.
+     */
+    private static buildPinoOptions;
+    /**
+     * Создаёт инстанс pino. Воркер транспорта переиспользуется, если объект
+     * конфига транспорта тот же по ссылке (сравнение identity, не по значению).
+     * Это покрывает связку reconfigure→applyInstrumentations (между ними
+     * this.opts.transport не пересобирается) и не даёт пересоздавать и тут же
+     * закрывать только что поднятый, возможно медленный, OTEL-воркер. Новый
+     * объект конфига (например, при config.onUpdate) ожидаемо пересоздаёт воркер.
+     */
+    private static instantiatePino;
+    /**
+     * Поднимает worker-транспорт, закрыв предыдущий. Обработчик 'error' не даёт
+     * асинхронной ошибке воркера уронить процесс, но делает её видимой в stderr
+     * (сам логгер использовать нельзя — упал его транспорт). Ошибку резолва
+     * таргета pino.transport(...) бросает синхронно — она долетает до старта.
+     */
+    private static createTransport;
+    /**
+     * Завершает воркеры предыдущего транспорта (best-effort, не блокируя). stdout
+     * не затрагивается: для него хэндл не сохраняется.
+     */
+    private static disposeActiveTransport;
 }

package/dist/logger.factory.js

@@ -6,6 +6,7 @@ const logger_metadata_registry_1 = require("./metadata/logger-metadata.registry"
 const defaults_1 = require("./defaults");
 const implementations_1 = require("./implementations");
 const types_1 = require("./types");
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1000;
 /**
  * ATTENTION: require('pino') тут не просто так, в общем они нужны для корректной работы хуков из `@opentelemetry/instrumentation-pino`
  */
@@ -47,13 +48,10 @@ class LoggerFactory {
         timestamp: this.pinoTimestampFormatMap[this.opts.timestampFormat],
     });
     static _serializers = null;
-    static get pinoConfig() {
-        const { timestampFormat, ...other } = this.opts;
-        return {
-            ...other,
-            timestamp: this.pinoTimestampFormatMap[timestampFormat],
-        };
-    }
+    /** Ссылка на активный worker-транспорт для закрытия его воркеров. */
+    static _activeTransport = null;
+    /** Конфиг, по которому собран _activeTransport (для переиспользования воркера). */
+    static _activeTransportConfig = null;
     /**
      * Переконфигурация pino нужна потому, что изначально логгер инициализируется
      * с дефолтными настройками, т. к. конфигурация ещё не прочитана.
@@ -63,8 +61,7 @@ class LoggerFactory {
      */
     static reconfigure(opts) {
         this.applyOptions(opts);
-        const { stream, ...other } = this.pinoConfig;
-        this._globalPino = requirePino()(other, stream);
+        this._globalPino = this.instantiatePino();
     }
     /**
      * Этот метод должен быть вызван после того, как подключен instrumentation-pino.
@@ -82,11 +79,7 @@ class LoggerFactory {
      * при помощи cli - можно немного упростить архитектуру
      */
     static applyInstrumentations(logHookFunction) {
-        const { stream, ...other } = this.opts;
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        this._globalPino = requirePino()({
-            ...other,
-            timestamp: this.pinoTimestampFormatMap[this.opts.timestampFormat],
+        this._globalPino = this.instantiatePino({
             /**
              * Функция которая позволяет добавить дополнительные данные в логи Pino
              */
@@ -106,7 +99,36 @@ class LoggerFactory {
                     },
                 }
                 : {},
-        }, stream);
+        });
+    }
+    /**
+     * Сливает буфер worker-транспорта и завершает его воркеры. Без вызова на
+     * остановке приложения забуференные логи теряются, а воркеры висят.
+     */
+    static async shutdown(timeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS) {
+        const stream = this._activeTransport;
+        if (!stream)
+            return;
+        this._activeTransport = null;
+        this._activeTransportConfig = null;
+        await new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve();
+            };
+            try {
+                stream.on('close', finish);
+                stream.flush(() => stream.end());
+            }
+            catch {
+                finish();
+            }
+            const timer = setTimeout(finish, timeoutMs);
+            timer.unref?.();
+        });
     }
     static onMessage(handler) {
         this.events.on('msg', handler);
@@ -159,13 +181,105 @@ class LoggerFactory {
         return this._serializers.has(name);
     }
     static applyOptions(opts) {
-        const { redact, level, stream, timestampFormat } = opts || {};
-        Object.assign(this.opts, {
-            redact,
+        const { redact, level, stream, transport, timestampFormat } = opts || {};
+        const base = {
+            redact: redact ?? this.opts.redact ?? [],
             level: level ?? defaults_1.DEFAULT_LEVEL,
-            stream: stream ?? requirePino().destination(),
             timestampFormat: timestampFormat ?? types_1.LogTimestampFormat.isoTime,
+        };
+        /**
+         * Выбираем ровно один способ доставки. Если ни stream, ни transport не
+         * переданы — сохраняем текущий, чтобы частичный reconfigure({ level }) не
+         * сбрасывал ранее заданный transport.
+         */
+        if (transport) {
+            this.opts = { ...base, transport };
+        }
+        else if (stream) {
+            this.opts = { ...base, stream };
+        }
+        else if (this.opts.transport) {
+            this.opts = { ...base, transport: this.opts.transport };
+        }
+        else {
+            this.opts = {
+                ...base,
+                stream: this.opts.stream ?? requirePino().destination(),
+            };
+        }
+    }
+    /**
+     * `stream`/`transport` исключаем из опций: способ доставки задаётся вторым
+     * аргументом `pino()`, а pino запрещает одновременно `transport` в опциях и
+     * stream-аргумент.
+     */
+    static buildPinoOptions(extra = {}) {
+        const { timestampFormat, stream: _stream, transport: _transport, ...other } = this.opts;
+        return {
+            ...other,
+            timestamp: this.pinoTimestampFormatMap[timestampFormat],
+            ...extra,
+        };
+    }
+    /**
+     * Создаёт инстанс pino. Воркер транспорта переиспользуется, если объект
+     * конфига транспорта тот же по ссылке (сравнение identity, не по значению).
+     * Это покрывает связку reconfigure→applyInstrumentations (между ними
+     * this.opts.transport не пересобирается) и не даёт пересоздавать и тут же
+     * закрывать только что поднятый, возможно медленный, OTEL-воркер. Новый
+     * объект конфига (например, при config.onUpdate) ожидаемо пересоздаёт воркер.
+     */
+    static instantiatePino(extra = {}) {
+        const pino = requirePino();
+        const options = this.buildPinoOptions(extra);
+        if (!this.opts.transport) {
+            this.disposeActiveTransport();
+            return pino(options, this.opts.stream);
+        }
+        const reuse = this._activeTransport &&
+            this.opts.transport === this._activeTransportConfig;
+        const stream = reuse
+            ? this._activeTransport
+            : this.createTransport(this.opts.transport);
+        return pino(options, stream);
+    }
+    /**
+     * Поднимает worker-транспорт, закрыв предыдущий. Обработчик 'error' не даёт
+     * асинхронной ошибке воркера уронить процесс, но делает её видимой в stderr
+     * (сам логгер использовать нельзя — упал его транспорт). Ошибку резолва
+     * таргета pino.transport(...) бросает синхронно — она долетает до старта.
+     */
+    static createTransport(transport) {
+        this.disposeActiveTransport();
+        const stream = requirePino().transport(transport);
+        stream.on('error', (...args) => {
+            const error = args[0];
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[@rsdk/logging] transport error: ${message}\n`);
         });
+        this._activeTransport = stream;
+        this._activeTransportConfig = transport;
+        return stream;
+    }
+    /**
+     * Завершает воркеры предыдущего транспорта (best-effort, не блокируя). stdout
+     * не затрагивается: для него хэндл не сохраняется.
+     */
+    static disposeActiveTransport() {
+        const previous = this._activeTransport;
+        if (!previous)
+            return;
+        this._activeTransport = null;
+        this._activeTransportConfig = null;
+        // на teardown ошибки ожидаемы (например, "end() took too long" у медленных
+        // транспортов) — глушим их молча и не держим event loop
+        previous.unref?.();
+        previous.removeAllListeners?.('error');
+        previous.on('error', () => { });
+        try {
+            previous.end();
+        }
+        catch { }
     }
 }
 exports.LoggerFactory = LoggerFactory;

package/dist/logger.factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.factory.js","sourceRoot":"","sources":["../src/logger.factory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"logger.factory.js","sourceRoot":"","sources":["../src/logger.factory.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { Constructor } from '@rsdk/common';
 import type pino from 'pino';
+import type { TransportMultiOptions } from 'pino';
 export declare enum LogLevel {
     fatal = "fatal",
     error = "error",
@@ -16,12 +17,23 @@ export declare enum LogTimestampFormat {
 }
 export type TimeFn = () => string;
 export type Params = Record<string, unknown>;
-export interface LoggerOptions {
+export interface LoggerOptionsBase {
     level: LogLevel;
     redact: string[];
-    stream: pino.DestinationStream;
     timestampFormat: LogTimestampFormat;
 }
+/**
+ * `stream` и `transport` — взаимоисключающие способы доставки (pino не
+ * принимает оба сразу). Это закодировано в типе: задание одного запрещает
+ * другой.
+ */
+export type LoggerOptions = LoggerOptionsBase & ({
+    stream?: pino.DestinationStream;
+    transport?: never;
+} | {
+    stream?: never;
+    transport?: TransportMultiOptions;
+});
 export type LoggingContext = string | Constructor;
 export type OnMessage = (level: LogLevel, data: Record<string, unknown>) => void;
 export interface LoggerSerializerMetadata {

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAGA,IAAY,QAOX;AAPD,WAAY,QAAQ;IAClB,2BAAe,CAAA;IACf,2BAAe,CAAA;IACf,yBAAa,CAAA;IACb,yBAAa,CAAA;IACb,2BAAe,CAAA;IACf,2BAAe,CAAA;AACjB,CAAC,EAPW,QAAQ,wBAAR,QAAQ,QAOnB;AAED,IAAY,kBAKX;AALD,WAAY,kBAAkB;IAC5B,6CAAuB,CAAA;IACvB,2CAAqB,CAAA;IACrB,2CAAqB,CAAA;IACrB,yCAAmB,CAAA;AACrB,CAAC,EALW,kBAAkB,kCAAlB,kBAAkB,QAK7B"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAIA,IAAY,QAOX;AAPD,WAAY,QAAQ;IAClB,2BAAe,CAAA;IACf,2BAAe,CAAA;IACf,yBAAa,CAAA;IACb,yBAAa,CAAA;IACb,2BAAe,CAAA;IACf,2BAAe,CAAA;AACjB,CAAC,EAPW,QAAQ,wBAAR,QAAQ,QAOnB;AAED,IAAY,kBAKX;AALD,WAAY,kBAAkB;IAC5B,6CAAuB,CAAA;IACvB,2CAAqB,CAAA;IACrB,2CAAqB,CAAA;IACrB,yCAAmB,CAAA;AACrB,CAAC,EALW,kBAAkB,kCAAlB,kBAAkB,QAK7B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsdk/logging",
-  "version": "5.12.0",
+  "version": "5.13.0-next.0",
   "description": "Base framework independent logging functionality",
   "license": "Apache License 2.0",
   "publishConfig": {
@@ -18,5 +18,5 @@
     "reflect-metadata": "^0.1.12 || ^0.2.0",
     "rxjs": "^7.1.0"
   },
-  "gitHead": "e37dbd5dfabbc6150e3d22d545b03ee5e41bf6a4"
+  "gitHead": "6efbb4a745c7e9cf44c5c71b6365ffb290820894"
 }

package/src/logger.factory.ts

@@ -4,6 +4,7 @@ import type {
   DestinationStream,
   Logger as Pino,
   LoggerOptions as LoggerOptsPino,
+  TransportMultiOptions,
 } from 'pino';
 
 import { LoggerMetadataRegistry } from './metadata/logger-metadata.registry';
@@ -12,6 +13,7 @@ import { PinoLogger } from './implementations';
 import type { ILogger, LogSerializerBase } from './logger.interface';
 import type {
   LoggerOptions,
+  LoggerOptionsBase,
   LoggerSerializerMetadata,
   LoggingContext,
   LogLevel,
@@ -20,6 +22,18 @@ import type {
 } from './types';
 import { LogTimestampFormat } from './types';
 
+/** Хэндл worker-транспорта pino (thread-stream) для teardown воркеров. */
+interface TransportStream extends DestinationStream {
+  end(): void;
+  flush(cb?: (err?: Error) => void): void;
+  flushSync(): void;
+  unref(): void;
+  on(event: string, listener: (...args: unknown[]) => void): void;
+  removeAllListeners(event?: string): void;
+}
+
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1000;
+
 /**
  * ATTENTION: require('pino') тут не просто так, в общем они нужны для корректной работы хуков из `@opentelemetry/instrumentation-pino`
  */
@@ -36,7 +50,7 @@ export class LoggerFactory {
   // eslint-disable-next-line unicorn/prefer-event-target
   private static readonly events = new EventEmitter();
 
-  private static readonly opts: LoggerOptions = {
+  private static opts: LoggerOptions = {
     level: DEFAULT_LEVEL,
     redact: [],
     stream: requirePino().destination(),
@@ -67,16 +81,11 @@ export class LoggerFactory {
 
   private static _serializers: Map<string, LogSerializerBase> | null = null;
 
-  private static get pinoConfig(): LoggerOptsPino & {
-    stream: DestinationStream;
-  } {
-    const { timestampFormat, ...other } = this.opts;
+  /** Ссылка на активный worker-транспорт для закрытия его воркеров. */
+  private static _activeTransport: TransportStream | null = null;
 
-    return {
-      ...other,
-      timestamp: this.pinoTimestampFormatMap[timestampFormat],
-    };
-  }
+  /** Конфиг, по которому собран _activeTransport (для переиспользования воркера). */
+  private static _activeTransportConfig: TransportMultiOptions | null = null;
 
   /**
    * Переконфигурация pino нужна потому, что изначально логгер инициализируется
@@ -88,9 +97,7 @@ export class LoggerFactory {
   static reconfigure(opts: Partial<LoggerOptions>): void {
     this.applyOptions(opts);
 
-    const { stream, ...other } = this.pinoConfig;
-
-    this._globalPino = requirePino()(other, stream);
+    this._globalPino = this.instantiatePino();
   }
 
   /**
@@ -111,39 +118,63 @@ export class LoggerFactory {
   static applyInstrumentations<T extends Record<string, any>>(
     logHookFunction?: (record: T) => void,
   ): void {
-    const { stream, ...other } = this.opts;
-
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    this._globalPino = requirePino()(
-      {
-        ...other,
-        timestamp: this.pinoTimestampFormatMap[this.opts.timestampFormat],
-
-        /**
-         * Функция которая позволяет добавить дополнительные данные в логи Pino
-         */
-        hooks: logHookFunction
-          ? {
-              /**
-               * Реализация взята с официальной документации
-               * https://getpino.io/#/docs/api?id=logmethod
-               */
-              logMethod: function (
-                inputArgs: any[],
-                method: Function,
-              ): unknown {
-                const arg1 = inputArgs[0];
-                if (arg1 && typeof arg1 === 'object') {
-                  logHookFunction(arg1 as T);
-                }
-                // eslint-disable-next-line unicorn/prefer-reflect-apply
-                return method.apply(this, inputArgs);
-              },
-            }
-          : {},
-      },
-      stream,
-    );
+    this._globalPino = this.instantiatePino({
+      /**
+       * Функция которая позволяет добавить дополнительные данные в логи Pino
+       */
+      hooks: logHookFunction
+        ? {
+            /**
+             * Реализация взята с официальной документации
+             * https://getpino.io/#/docs/api?id=logmethod
+             */
+            logMethod: function (inputArgs: any[], method: Function): unknown {
+              const arg1 = inputArgs[0];
+              if (arg1 && typeof arg1 === 'object') {
+                logHookFunction(arg1 as T);
+              }
+              // eslint-disable-next-line unicorn/prefer-reflect-apply
+              return method.apply(this, inputArgs);
+            },
+          }
+        : {},
+    });
+  }
+
+  /**
+   * Сливает буфер worker-транспорта и завершает его воркеры. Без вызова на
+   * остановке приложения забуференные логи теряются, а воркеры висят.
+   */
+  static async shutdown(
+    timeoutMs: number = DEFAULT_SHUTDOWN_TIMEOUT_MS,
+  ): Promise<void> {
+    const stream = this._activeTransport;
+
+    if (!stream) return;
+
+    this._activeTransport = null;
+    this._activeTransportConfig = null;
+
+    await new Promise<void>((resolve) => {
+      let settled = false;
+
+      const finish = (): void => {
+        if (settled) return;
+        settled = true;
+        resolve();
+      };
+
+      try {
+        stream.on('close', finish);
+        stream.flush(() => stream.end());
+      } catch {
+        finish();
+      }
+
+      const timer = setTimeout(finish, timeoutMs);
+
+      timer.unref?.();
+    });
   }
 
   static onMessage(handler: OnMessage): void {
@@ -212,13 +243,130 @@ export class LoggerFactory {
   }
 
   private static applyOptions(opts: Partial<LoggerOptions>): void {
-    const { redact, level, stream, timestampFormat } = opts || {};
+    const { redact, level, stream, transport, timestampFormat } = opts || {};
 
-    Object.assign(this.opts, {
-      redact,
+    const base: LoggerOptionsBase = {
+      redact: redact ?? this.opts.redact ?? [],
       level: level ?? DEFAULT_LEVEL,
-      stream: stream ?? requirePino().destination(),
       timestampFormat: timestampFormat ?? LogTimestampFormat.isoTime,
+    };
+
+    /**
+     * Выбираем ровно один способ доставки. Если ни stream, ни transport не
+     * переданы — сохраняем текущий, чтобы частичный reconfigure({ level }) не
+     * сбрасывал ранее заданный transport.
+     */
+    if (transport) {
+      this.opts = { ...base, transport };
+    } else if (stream) {
+      this.opts = { ...base, stream };
+    } else if (this.opts.transport) {
+      this.opts = { ...base, transport: this.opts.transport };
+    } else {
+      this.opts = {
+        ...base,
+        stream: this.opts.stream ?? requirePino().destination(),
+      };
+    }
+  }
+
+  /**
+   * `stream`/`transport` исключаем из опций: способ доставки задаётся вторым
+   * аргументом `pino()`, а pino запрещает одновременно `transport` в опциях и
+   * stream-аргумент.
+   */
+  private static buildPinoOptions(
+    extra: Partial<LoggerOptsPino> = {},
+  ): LoggerOptsPino {
+    const {
+      timestampFormat,
+      stream: _stream,
+      transport: _transport,
+      ...other
+    } = this.opts;
+
+    return {
+      ...other,
+      timestamp: this.pinoTimestampFormatMap[timestampFormat],
+      ...extra,
+    };
+  }
+
+  /**
+   * Создаёт инстанс pino. Воркер транспорта переиспользуется, если объект
+   * конфига транспорта тот же по ссылке (сравнение identity, не по значению).
+   * Это покрывает связку reconfigure→applyInstrumentations (между ними
+   * this.opts.transport не пересобирается) и не даёт пересоздавать и тут же
+   * закрывать только что поднятый, возможно медленный, OTEL-воркер. Новый
+   * объект конфига (например, при config.onUpdate) ожидаемо пересоздаёт воркер.
+   */
+  private static instantiatePino(extra: Partial<LoggerOptsPino> = {}): Pino {
+    const pino = requirePino();
+    const options = this.buildPinoOptions(extra);
+
+    if (!this.opts.transport) {
+      this.disposeActiveTransport();
+
+      return pino(options, this.opts.stream);
+    }
+
+    const reuse =
+      this._activeTransport &&
+      this.opts.transport === this._activeTransportConfig;
+
+    const stream = reuse
+      ? this._activeTransport!
+      : this.createTransport(this.opts.transport);
+
+    return pino(options, stream);
+  }
+
+  /**
+   * Поднимает worker-транспорт, закрыв предыдущий. Обработчик 'error' не даёт
+   * асинхронной ошибке воркера уронить процесс, но делает её видимой в stderr
+   * (сам логгер использовать нельзя — упал его транспорт). Ошибку резолва
+   * таргета pino.transport(...) бросает синхронно — она долетает до старта.
+   */
+  private static createTransport(
+    transport: TransportMultiOptions,
+  ): TransportStream {
+    this.disposeActiveTransport();
+
+    const stream = requirePino().transport(transport) as TransportStream;
+
+    stream.on('error', (...args: unknown[]) => {
+      const error = args[0];
+      const message = error instanceof Error ? error.message : String(error);
+
+      process.stderr.write(`[@rsdk/logging] transport error: ${message}\n`);
     });
+
+    this._activeTransport = stream;
+    this._activeTransportConfig = transport;
+
+    return stream;
+  }
+
+  /**
+   * Завершает воркеры предыдущего транспорта (best-effort, не блокируя). stdout
+   * не затрагивается: для него хэндл не сохраняется.
+   */
+  private static disposeActiveTransport(): void {
+    const previous = this._activeTransport;
+
+    if (!previous) return;
+
+    this._activeTransport = null;
+    this._activeTransportConfig = null;
+
+    // на teardown ошибки ожидаемы (например, "end() took too long" у медленных
+    // транспортов) — глушим их молча и не держим event loop
+    previous.unref?.();
+    previous.removeAllListeners?.('error');
+    previous.on('error', () => {});
+
+    try {
+      previous.end();
+    } catch {}
   }
 }

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { Constructor } from '@rsdk/common';
 import type pino from 'pino';
+import type { TransportMultiOptions } from 'pino';
 
 export enum LogLevel {
   fatal = 'fatal',
@@ -16,17 +17,28 @@ export enum LogTimestampFormat {
   nullTime = 'nullTime',
   isoTime = 'isoTime',
 }
+
 export type TimeFn = () => string;
 
 export type Params = Record<string, unknown>;
 
-export interface LoggerOptions {
+export interface LoggerOptionsBase {
   level: LogLevel;
   redact: string[];
-  stream: pino.DestinationStream;
   timestampFormat: LogTimestampFormat;
 }
 
+/**
+ * `stream` и `transport` — взаимоисключающие способы доставки (pino не
+ * принимает оба сразу). Это закодировано в типе: задание одного запрещает
+ * другой.
+ */
+export type LoggerOptions = LoggerOptionsBase &
+  (
+    | { stream?: pino.DestinationStream; transport?: never }
+    | { stream?: never; transport?: TransportMultiOptions }
+  );
+
 export type LoggingContext = string | Constructor;
 
 export type OnMessage = (