Основные понятия

Логгер (Logger)

Главный класс, который предоставляет методы execute (запись сообщения) и read (запрос ввода от пользователя). Он наследует абстрактный BaseLogger и добавляет конкретную реализацию.

Уровни логирования

Уровни определяются через объект LoggerLevels, который содержит:

levels — соответствие имени уровня числовому приоритету (чем больше число, тем выше приоритет).
level — текущий активный уровень. Сообщения с приоритетом меньше этого уровня игнорируются.

Пример:

const levels: LoggerLevels<{ debug: 0; info: 1; warn: 2; error: 3 }> = {
  levels: { debug: 0, info: 1, warn: 2, error: 3 },
  level: "warn", // будут выводиться только warn и error
};

Контекст вызова

Каждый вызов execute или read принимает объект контекста, который определяет поведение для конкретного сообщения:

level — уровень сообщения (обязателен).
log — выводить ли сообщение в консоль (по умолчанию true).
writeFile — записывать ли сообщение в файл (по умолчанию false).
separator — разделитель между частями сообщения (по умолчанию \n).

Контекст может быть переопределён на уровне вызова, при этом он объединяется с базовым контекстом, переданным в конструктор.

Сервисы

Библиотека предоставляет два основных сервиса:

FileService — управляет файлом лога: чтение, запись (добавление в конец), перезапись, удаление. Автоматически создаёт директорию, если её нет.
TimestampService — генерирует временные метки. Поддерживает форматирование через собственную функцию, локали и часовые пояса.

Форматтеры

Форматтеры преобразуют входные данные (массив значений) в строку. Встроены:

DefaultFormatter — вызывает toString() у объектов.
ErrorFormatter — форматирует ошибки с именем, сообщением, причиной и стеком.
NullableFormatter — преобразует null и undefined в строки.
FormatterHandler — цепочка форматтеров, которые применяются последовательно.

Вы можете создавать свои форматтеры, наследуя BaseFormatter.

Аффиксы

Аффиксы — это префиксы или суффиксы, добавляемые к сообщению. Например, имя логгера или временная метка. Библиотека поставляется с:

NamePrefix — добавляет имя логгера.
TimestampPrefix — добавляет временную метку.

Аффиксы применяются в порядке, заданном в AffixHandler.