letopis 2.0.0 → 3.0.0

package/dist/log.d.ts

@@ -0,0 +1,121 @@
+import { type LogEventLevel, type LogEventName } from './messages/index.js';
+import type { LogEvent, LogFn, LogOptions } from './types.js';
+export type { LogEventLevel, LogEventName } from './messages/index.js';
+export type { LogEvent, LogFn, LogLevel, LogObject, LogOptions, Logger } from './types.js';
+/** Поля события, которые задаёт место вызова. */
+export type LogFields = Partial<Omit<LogEvent, 'ts' | 'event' | 'level'>> & {
+    level?: LogEventLevel;
+};
+/** Строка без секретов: учётные данные в строке подключения, пароль параметром и в тексте SQL. */
+export declare function maskText(s: string): string;
+type Sink = (level: LogEventLevel, ev: LogEvent) => void;
+/** Кто действует: арендатор и аккаунт фасада — считаются в момент события. */
+export interface LogBound {
+    who?: () => {
+        tenant?: string | null;
+        account?: string | null;
+    };
+    tx?: string;
+    /** Счётчик операций записи явной транзакции (db.begin()): по нему уровень tx.commit — info, если запись была. */
+    writes?: {
+        n: number;
+    };
+}
+/**
+ * Текст ошибки для предупреждения или события: у ошибки PostgreSQL — только «PostgreSQL <SQLSTATE>» (без её текста),
+ * у прочих — текст без паролей.
+ */
+export declare function safeErrorText(e: unknown): string;
+/** Уровень события error: warn — штатный отказ (EXPECTED_CODES, нарушения данных), иначе error. */
+export declare function errorLevel(e: unknown): LogEventLevel;
+/**
+ * Поля события error по ошибке: код, ключ каталога, текст, подробности, причина. Ошибка PostgreSQL (сама или причиной)
+ * — только SQLSTATE и имена объектов схемы: её текст, DETAIL, WHERE и HINT в событие не идут.
+ */
+export declare function errorFields(e: unknown): LogFields;
+/**
+ * Логгер подключения: приёмник, порог, имена полей для маскировки и привязка (кто действует, метка транзакции).
+ * Производные фасады (db.as(), db.begin(), батч) получают child() — тот же приёмник и порог.
+ */
+export declare class Log {
+    private readonly sink;
+    private readonly min;
+    private readonly redactKeys;
+    private readonly bound;
+    constructor(sink: Sink | null, min: number, redactKeys: ReadonlySet<string>, bound?: LogBound);
+    /** Хоть одно событие может уйти (есть приёмник и порог не off). */
+    get enabled(): boolean;
+    /** Логгер задан (log или LETOPIS_LOG): предупреждения идут в него, а не в console.warn. */
+    get active(): boolean;
+    /** Метка транзакции привязки. */
+    get tx(): string | undefined;
+    /** Операций записи в явной транзакции привязки (undefined — привязки к db.begin() нет). */
+    get writes(): number | undefined;
+    /** Учесть удавшуюся операцию в счётчике записи транзакции — до проверки порога, событие может и не уйти. */
+    mark(event: string): void;
+    /** Уровень проходит порог. */
+    level(l: LogEventLevel): boolean;
+    /** Событие (его уровень по каталогу) проходит порог — проверка до сборки полей. */
+    wants(event: LogEventName): boolean;
+    child(b: LogBound): Log;
+    /** Событие: уровень — из каталога (или fields.level); ниже порога — ничего. */
+    emit(event: LogEventName, f?: LogFields): void;
+    /**
+     * Событие error по ошибке; одна ошибка — одно событие. Уровень — errorLevel: штатный отказ (exists, conflict,
+     * target_not_found, нарушения данных и т. п.) — warn, прочее — error.
+     */
+    error(e: unknown, f?: LogFields): void;
+    /** Предупреждение: событие warning (ключ каталога и текст). */
+    warning(key: string | undefined, msg: string, detail?: Record<string, unknown>): void;
+    /** Имя поля — секрет: всегда или по redact. */
+    secret(key: string): boolean;
+    /** Значение для события: секреты — '***', строки без паролей, массивы и вложенность ограничены. */
+    clean(v: unknown, depth?: number, key?: string): unknown;
+    private build;
+}
+/** Логирование выключено: ни приёмника, ни событий. */
+export declare const NOLOG: Log;
+/** Логгер-функция: события JSON-строками в stderr (LETOPIS_LOG, флаг CLI --log). */
+export declare const stderrLog: LogFn;
+/**
+ * Уровень из LETOPIS_LOG: `debug|info|warn|error`; `1`, `true`, `yes`, `on` и прочее непустое — `info`; не задана, пусто,
+ * `0`, `false`, `no`, `off` — логирования по переменной нет.
+ */
+export declare function envLevel(v?: string | undefined): LogEventLevel | undefined;
+/**
+ * Логгер по опциям: log (или stderr по LETOPIS_LOG), порог logLevel (или из LETOPIS_LOG, иначе 'info'), redact. Неверные
+ * опции — invalid_data (log.bad_level, log.bad_logger, log.bad_redact) до подключения.
+ */
+export declare function makeLog(o?: LogOptions): Log;
+/** Логгер по одной LETOPIS_LOG — для мест без подключения (предупреждения, createTenant). */
+export declare function envLog(): Log;
+/** Метка транзакции: b — db.begin(), t — db.transaction(); номер в процессе. */
+export declare const nextTx: (kind: "b" | "t") => string;
+/** Строка подключения без пароля. */
+export declare const maskDsn: (dsn: string | undefined) => string | undefined;
+/**
+ * Операция с событием: время, событие успеха (done может дополнить поля, сменить событие или вернуть null — без
+ * события) и error при отказе. Выключенный логгер — сам вызов без обёртки.
+ */
+export declare function traced<T>(log: Log, event: LogEventName | null, f: LogFields, fn: () => Promise<T>, done?: (r: T) => (LogFields & {
+    event?: LogEventName;
+}) | null | undefined): Promise<T>;
+/** Синхронный вызов: ошибка — событие error и проброс (шаги и модификаторы цепочки, Proxy фасада). */
+export declare function guarded<T>(log: Log, f: LogFields | (() => LogFields), fn: () => T): T;
+/** Что записать о вызове метода API: событие и поля; null — без события (ошибка пишется всё равно). */
+export type CallSpec = (args: unknown[], result: unknown, before: unknown) => (LogFields & {
+    event: LogEventName;
+}) | null;
+/**
+ * Обёртка API-объекта (db.auth, db.acl): каждый метод — время, событие по spec и error при отказе. pre — снимок до вызова
+ * (например, прежний арендатор у auth.switch). Выключенный логгер — тот же объект.
+ */
+export declare function instrument<T extends object>(api: T, log: Log, area: string, specs: Readonly<Record<string, CallSpec>>, pre?: Readonly<Record<string, () => unknown>>): T;
+/** Текст запроса для события: одной строкой, без паролей, не длиннее 2000 символов. */
+export declare function sqlText(text: string): string;
+/**
+ * Пул postgres.js (или зарезервированное соединение, транзакция), каждый запрос которого даёт событие sql: шаблон
+ * sql`…`, unsafe(), а также соединения reserve() и транзакции begin()/savepoint(). Только при пороге debug — иначе тот
+ * же объект. Значения параметров в событие не попадают.
+ */
+export declare function traceSql<S extends object>(sql: S, log: Log): S;