@verdeect/kit 0.0.0-stage → 1.0.0-rc.1

package/dist/config/helpers.js

@@ -0,0 +1,62 @@
+// Помощники zod для схем окружения (prd.md §3.1); эталон — O env.schema.ts + port/httpUrl из B.
+// Умолчание необязательно у всех помощников: без него ключ обязателен. Issue без входного значения (NFR-4).
+import { z } from 'zod';
+/** TCP-порт 0–65535; 0 — порт выбирает ОС (тесты). Пустая строка даёт 0, как в эталоне (§3.1). */
+export function port(fallback) {
+    const schema = z.coerce.number().int().min(0).max(65535);
+    return fallback === undefined ? schema : schema.default(fallback);
+}
+/** Целое > 0 (§3.1). */
+export function positiveInt(fallback) {
+    const schema = z.coerce.number().int().positive();
+    return fallback === undefined ? schema : schema.default(fallback);
+}
+/** Целое ≥ 0; внутренний помощник фрагментов, из /config не реэкспортируется. */
+export function nonNegativeInt(fallback) {
+    const schema = z.coerce.number().int().nonnegative();
+    return fallback === undefined ? schema : schema.default(fallback);
+}
+/** Необязательный текст: пусто или пробелы → null, иначе значение без крайних пробелов (§3.1). */
+export function optionalText() {
+    return z
+        .string()
+        .default('')
+        .transform((value) => (value.trim() === '' ? null : value.trim()));
+}
+/** Только строки `true`/`false`: приведение zod к boolean сделало бы строку `false` истиной (§3.1). */
+export function booleanFlag(fallback) {
+    const schema = z.enum(['true', 'false']);
+    const withDefault = fallback === undefined ? schema : schema.default(fallback ? 'true' : 'false');
+    return withDefault.transform((value) => value === 'true');
+}
+/**
+ * Ключ с JSON-значением (§3.1). Умолчание — строка до разбора: в zod 4 умолчание после
+ * преобразования ожидает уже разобранный тип. Ошибка разбора — без входного значения.
+ */
+export function jsonValue(schema, fallback) {
+    const raw = fallback === undefined ? z.string() : z.string().default(fallback);
+    return raw
+        .transform((value, ctx) => {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', message: 'неверный JSON', input: '' });
+            return z.NEVER;
+        }
+    })
+        .pipe(schema);
+}
+/** Адрес HTTP-ресурса: только http и https (§3.1). */
+export function httpUrl() {
+    return z.url({ protocol: /^https?$/ });
+}
+/** Значения поля `key` элементов массива не повторяются; для `superRefine`, issue — без значений (§3.1). */
+export function uniqueBy(key) {
+    return (items, ctx) => {
+        const seen = new Set(items.map((item) => item[key]));
+        if (seen.size !== items.length) {
+            ctx.addIssue({ code: 'custom', message: `повтор ${String(key)}`, input: '' });
+        }
+    };
+}

package/dist/config/index.d.ts

@@ -0,0 +1,7 @@
+export { migrateEnvSchema, prepareEnvSchema } from './cli-schemas.js';
+export { defineEnv, withBaseChecks } from './define-env.js';
+export { envBase, envCrypto, envDatabase, envMessaging, envRedis, envSentry, envServiceUrls, } from './fragments.js';
+export type { KitBaseEnv, KitCryptoEnv, KitDatabaseEnv, KitMessagingEnv, KitRedisEnv, } from './fragments.js';
+export { booleanFlag, httpUrl, jsonValue, optionalText, port, positiveInt, uniqueBy, } from './helpers.js';
+export { KitConfigModule } from './kit-config.module.js';
+export { InvalidEnvironmentError, parseEnv } from './parse-env.js';

package/dist/config/index.js

@@ -0,0 +1,7 @@
+// Точка входа @verdeect/kit/config (prd.md §3.1, E1): явный список экспортов.
+export { migrateEnvSchema, prepareEnvSchema } from './cli-schemas.js';
+export { defineEnv, withBaseChecks } from './define-env.js';
+export { envBase, envCrypto, envDatabase, envMessaging, envRedis, envSentry, envServiceUrls, } from './fragments.js';
+export { booleanFlag, httpUrl, jsonValue, optionalText, port, positiveInt, uniqueBy, } from './helpers.js';
+export { KitConfigModule } from './kit-config.module.js';
+export { InvalidEnvironmentError, parseEnv } from './parse-env.js';

package/dist/config/kit-config.module.d.ts

@@ -0,0 +1,20 @@
+import type { DynamicModule } from '@nestjs/common';
+import type { z } from 'zod';
+/** Схема окружения: результат — объект ключей (его ожидает validate у ConfigModule). */
+type EnvSchema = z.ZodType<Record<string, unknown>>;
+/** Параметры KitConfigModule.forRoot. */
+export interface KitConfigModuleOptions<S extends EnvSchema> {
+    /** Схема окружения сервиса (обычно результат defineEnv). */
+    readonly schema: S;
+}
+/** Глобальный модуль окружения; разбирает окружение при каждой сборке контекста Nest (AC-1.7). */
+export declare class KitConfigModule {
+    /**
+     * Глобальный ConfigService с разобранным окружением. При запуске через `bootstrapService` окружение не
+     * разбирается повторно; иначе — `parseEnv(schema, process.env)` при сборке контекста, ошибка —
+     * `InvalidEnvironmentError`, сборка контекста отклоняется (сам `forRoot` не отклоняется). Файл `.env` не
+     * читается, в `process.env` ничего не пишется, ConfigService читает только разобранные значения.
+     */
+    static forRoot<S extends EnvSchema>(options: KitConfigModuleOptions<S>): Promise<DynamicModule>;
+}
+export {};

package/dist/config/kit-config.module.js

@@ -0,0 +1,23 @@
+import { ConfigModule } from '@nestjs/config';
+import { takePreparsedEnv } from '../internal/preparsed-env.js';
+import { parseEnv } from './parse-env.js';
+/** Глобальный модуль окружения; разбирает окружение при каждой сборке контекста Nest (AC-1.7). */
+export class KitConfigModule {
+    /**
+     * Глобальный ConfigService с разобранным окружением. При запуске через `bootstrapService` окружение не
+     * разбирается повторно; иначе — `parseEnv(schema, process.env)` при сборке контекста, ошибка —
+     * `InvalidEnvironmentError`, сборка контекста отклоняется (сам `forRoot` не отклоняется). Файл `.env` не
+     * читается, в `process.env` ничего не пишется, ConfigService читает только разобранные значения.
+     */
+    static forRoot(options) {
+        const { schema } = options;
+        return ConfigModule.forRoot({
+            isGlobal: true,
+            ignoreEnvFile: true,
+            // Без validate @nestjs/config копирует process.env сам в себя; false — копии нет совсем.
+            validatePredefined: false,
+            skipProcessEnv: true,
+            load: [() => takePreparsedEnv(schema) ?? parseEnv(schema, process.env)],
+        });
+    }
+}

package/dist/config/parse-env.d.ts

@@ -0,0 +1,14 @@
+import type { z } from 'zod';
+/** Ошибка окружения: только пути ключей, без значений (NFR-4). */
+export declare class InvalidEnvironmentError extends Error {
+    /** Код ошибки конфигурации. */
+    readonly code: "INVALID_ENVIRONMENT";
+    /** Полные пути ключей через точку, без дублей; без пути — `(root)`. */
+    readonly keys: readonly string[];
+    constructor(keys: readonly string[]);
+}
+/**
+ * Результат схемы или InvalidEnvironmentError (§3.1). Ошибка zod не сохраняется ни в `cause`, ни в
+ * полях: её issues содержат входные значения.
+ */
+export declare function parseEnv<S extends z.ZodType>(schema: S, env: Readonly<Record<string, unknown>>): z.output<S>;

package/dist/config/parse-env.js

@@ -0,0 +1,28 @@
+/** Ошибка окружения: только пути ключей, без значений (NFR-4). */
+export class InvalidEnvironmentError extends Error {
+    /** Код ошибки конфигурации. */
+    code = 'INVALID_ENVIRONMENT';
+    /** Полные пути ключей через точку, без дублей; без пути — `(root)`. */
+    keys;
+    constructor(keys) {
+        super(`Неверное окружение: ${keys.join(', ')}`);
+        this.name = 'InvalidEnvironmentError';
+        this.keys = keys;
+    }
+}
+/** Пути ключей issues без дублей, в порядке issues; значения и сообщения zod не берутся. */
+function issueKeys(error) {
+    const keys = error.issues.map((issue) => issue.path.length === 0 ? '(root)' : issue.path.map(String).join('.'));
+    return [...new Set(keys)];
+}
+/**
+ * Результат схемы или InvalidEnvironmentError (§3.1). Ошибка zod не сохраняется ни в `cause`, ни в
+ * полях: её issues содержат входные значения.
+ */
+export function parseEnv(schema, env) {
+    const result = schema.safeParse(env);
+    if (!result.success) {
+        throw new InvalidEnvironmentError(issueKeys(result.error));
+    }
+    return result.data;
+}

package/dist/crypto/cipher.d.ts

@@ -0,0 +1,61 @@
+/** Причина отказа `decrypt`: формат значения, версия ключа не в `keys`, проверка подлинности GCM. */
+export type DecryptErrorReason = 'format' | 'unknown_version' | 'auth';
+/** Опции `createCipher` (§3.6). */
+export interface KitCipherOptions {
+    /** Имя сервиса `^[a-z][a-z0-9-]{1,31}$`; входит в `info` HKDF. */
+    readonly service: string;
+    /** Ключи `[{version, secret}]` (как `ENCRYPTION_KEYS`); первый шифрует, остальные только читаются. */
+    readonly keys: readonly {
+        /** Версия ключа, целое ≥ 1; попадает в префикс значения `v<N>`. */
+        readonly version: number;
+        /** Секрет base64url без `=`, не короче 32 байт. */
+        readonly secret: string;
+    }[];
+    /** Назначение `^[a-z][a-z0-9-]{1,31}$`; разные назначения — разные ключи. */
+    readonly purpose: string;
+}
+/** Шифр одного назначения (§3.6). */
+export interface KitCipher {
+    /** Шифрует текст ключом `keys[0]`; результат — `v<N>:<iv>:<ct>:<tag>` (base64url). `aad` обязателен. */
+    encrypt(plaintext: string, opts: {
+        /** Привязка значения к записи, обычно `<purpose>:<id записи>`; непустая. */
+        readonly aad: string;
+    }): string;
+    /**
+     * Расшифровывает значение ключом его версии.
+     * @throws {DecryptError} `'format'`, `'unknown_version'` или `'auth'`.
+     */
+    decrypt(value: string, opts: {
+        /** Тот же `aad`, что при шифровании. */
+        readonly aad: string;
+    }): string;
+    /**
+     * `true`, если версия значения не совпадает с версией `keys[0]`.
+     * @throws {DecryptError} `'format'` — значение вне формата.
+     */
+    needsReencrypt(value: string): boolean;
+}
+/** Отказ расшифровки; текст и поля без открытого текста, `aad`, значения и ключей (NFR-4). */
+export declare class DecryptError extends Error {
+    /** Причина отказа. */
+    readonly reason: DecryptErrorReason;
+    /** @param reason причина отказа. */
+    constructor(reason: DecryptErrorReason);
+}
+/**
+ * Создаёт шифр AES-256-GCM для назначения `purpose` сервиса `service`. Ключ каждой версии — HKDF-SHA256 от
+ * декодированных байт секрета, соль пустая, `info = verdeect-<service>:<purpose>`, 32 байта; выводится один раз.
+ * `aad` значения — `<purpose>:<id записи>`: значение одной записи не расшифровывается в другой.
+ *
+ * Смена ключа (UC-10): 1) `verdeect-kit crypto generate-secret`; 2) новая версия первой в `ENCRYPTION_KEYS`, старая
+ * остаётся; 3) перезапуск всех реплик; 4) задача под `runExclusive` перешифровывает значения с
+ * `needsReencrypt(value) === true`; 5) старая версия убирается, когда значений под ней не осталось.
+ * @throws {TypeError} `service`, `purpose` вне формата или `keys` не по схеме `ENCRYPTION_KEYS` (пути без значений).
+ */
+export declare function createCipher(options: KitCipherOptions): KitCipher;
+/**
+ * Новый секрет для `ENCRYPTION_KEYS`: `bytes` случайных байт в base64url без `=`.
+ * @param bytes длина в байтах, целое ≥ 32 (по умолчанию 32).
+ * @throws {RangeError} `bytes` не целое или меньше 32.
+ */
+export declare function generateSecret(bytes?: number): string;

package/dist/crypto/cipher.js

@@ -0,0 +1,136 @@
+// Шифр секретов /crypto (prd.md §3.6, UC-10, AC-7.1–AC-7.5). Эталон — B identity-client session-cipher.ts (версия ключа
+// v<N>, AAD, версия из значения без перебора) + HKDF-SHA256 и строгие длины IV/тега из O private-key-cipher.ts
+// (OR-102 п. 7). Старые форматы не читаются (P0, N9).
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto';
+import { encryptionKeysSchema } from '../config/fragments.js';
+import { assertServiceName } from '../internal/service-name.js';
+const ALGORITHM = 'aes-256-gcm';
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const KEY_BYTES = 32;
+const MIN_SECRET_BYTES = 32;
+const PURPOSE_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;
+const VALUE_PATTERN = /^v([1-9]\d*):([A-Za-z0-9_-]+):([A-Za-z0-9_-]*):([A-Za-z0-9_-]+)$/;
+const DECRYPT_MESSAGES = {
+    format: 'значение шифра в неверном формате',
+    unknown_version: 'версии ключа значения нет в ENCRYPTION_KEYS',
+    auth: 'значение шифра не прошло проверку подлинности',
+};
+/** Отказ расшифровки; текст и поля без открытого текста, `aad`, значения и ключей (NFR-4). */
+export class DecryptError extends Error {
+    /** Причина отказа. */
+    reason;
+    /** @param reason причина отказа. */
+    constructor(reason) {
+        super(DECRYPT_MESSAGES[reason]);
+        this.name = 'DecryptError';
+        this.reason = reason;
+    }
+}
+/** Строгое декодирование части: только каноничный base64url (лишний символ или хвостовые биты — 'format'; KT-26 п. 2). */
+function decodePart(part) {
+    const bytes = Buffer.from(part, 'base64url');
+    if (bytes.toString('base64url') !== part) {
+        throw new DecryptError('format');
+    }
+    return bytes;
+}
+function parse(value) {
+    const match = VALUE_PATTERN.exec(value);
+    if (match === null) {
+        throw new DecryptError('format');
+    }
+    const [, version = '', iv = '', ct = '', tag = ''] = match;
+    const parsed = {
+        version: Number(version),
+        iv: decodePart(iv),
+        ct: decodePart(ct),
+        tag: decodePart(tag),
+    };
+    if (parsed.iv.length !== IV_BYTES || parsed.tag.length !== TAG_BYTES) {
+        throw new DecryptError('format');
+    }
+    return parsed;
+}
+function assertAad(aad, where) {
+    if (typeof aad !== 'string' || aad.length === 0) {
+        throw new TypeError(`${where}: aad обязателен — непустая строка`);
+    }
+}
+/**
+ * Создаёт шифр AES-256-GCM для назначения `purpose` сервиса `service`. Ключ каждой версии — HKDF-SHA256 от
+ * декодированных байт секрета, соль пустая, `info = verdeect-<service>:<purpose>`, 32 байта; выводится один раз.
+ * `aad` значения — `<purpose>:<id записи>`: значение одной записи не расшифровывается в другой.
+ *
+ * Смена ключа (UC-10): 1) `verdeect-kit crypto generate-secret`; 2) новая версия первой в `ENCRYPTION_KEYS`, старая
+ * остаётся; 3) перезапуск всех реплик; 4) задача под `runExclusive` перешифровывает значения с
+ * `needsReencrypt(value) === true`; 5) старая версия убирается, когда значений под ней не осталось.
+ * @throws {TypeError} `service`, `purpose` вне формата или `keys` не по схеме `ENCRYPTION_KEYS` (пути без значений).
+ */
+export function createCipher(options) {
+    const { service, purpose } = options;
+    assertServiceName(service, 'createCipher');
+    if (!PURPOSE_PATTERN.test(purpose)) {
+        throw new TypeError(`createCipher: purpose «${purpose}» вне формата ^[a-z][a-z0-9-]{1,31}$`);
+    }
+    const checked = encryptionKeysSchema.safeParse(options.keys);
+    if (!checked.success) {
+        const paths = checked.error.issues.map((issue) => ['keys', ...issue.path.map(String)].join('.'));
+        throw new TypeError(`createCipher: неверные keys: ${[...new Set(paths)].join(', ')}`);
+    }
+    const info = `verdeect-${service}:${purpose}`;
+    const keys = new Map(checked.data.map(({ version, secret }) => [
+        version,
+        Buffer.from(hkdfSync('sha256', Buffer.from(secret, 'base64url'), Buffer.alloc(0), info, KEY_BYTES)),
+    ]));
+    const [current] = checked.data;
+    const currentKey = current === undefined ? undefined : keys.get(current.version);
+    if (current === undefined || currentKey === undefined) {
+        // Недостижимо: схема требует min(1); проверка — для noUncheckedIndexedAccess.
+        throw new TypeError('createCipher: неверные keys: keys');
+    }
+    return {
+        encrypt(plaintext, { aad }) {
+            assertAad(aad, 'encrypt');
+            const iv = randomBytes(IV_BYTES);
+            const cipher = createCipheriv(ALGORITHM, currentKey, iv, { authTagLength: TAG_BYTES });
+            cipher.setAAD(Buffer.from(aad, 'utf8'));
+            const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+            const tag = cipher.getAuthTag();
+            return `v${current.version}:${iv.toString('base64url')}:${ct.toString('base64url')}:${tag.toString('base64url')}`;
+        },
+        decrypt(value, { aad }) {
+            assertAad(aad, 'decrypt');
+            const parsed = parse(value);
+            const key = keys.get(parsed.version);
+            if (key === undefined) {
+                throw new DecryptError('unknown_version');
+            }
+            const decipher = createDecipheriv(ALGORITHM, key, parsed.iv, {
+                authTagLength: TAG_BYTES,
+            });
+            decipher.setAAD(Buffer.from(aad, 'utf8'));
+            decipher.setAuthTag(parsed.tag);
+            try {
+                return Buffer.concat([decipher.update(parsed.ct), decipher.final()]).toString('utf8');
+            }
+            catch {
+                throw new DecryptError('auth');
+            }
+        },
+        needsReencrypt(value) {
+            return parse(value).version !== current.version;
+        },
+    };
+}
+/**
+ * Новый секрет для `ENCRYPTION_KEYS`: `bytes` случайных байт в base64url без `=`.
+ * @param bytes длина в байтах, целое ≥ 32 (по умолчанию 32).
+ * @throws {RangeError} `bytes` не целое или меньше 32.
+ */
+export function generateSecret(bytes = MIN_SECRET_BYTES) {
+    if (!Number.isInteger(bytes) || bytes < MIN_SECRET_BYTES) {
+        throw new RangeError('generateSecret: bytes — целое не меньше 32');
+    }
+    return randomBytes(bytes).toString('base64url');
+}

package/dist/crypto/index.d.ts

@@ -0,0 +1,2 @@
+export { createCipher, DecryptError, generateSecret } from './cipher.js';
+export type { DecryptErrorReason, KitCipher, KitCipherOptions } from './cipher.js';

package/dist/crypto/index.js

@@ -0,0 +1,2 @@
+// Точка входа @verdeect/kit/crypto (prd.md §3.6, E7): явный список экспортов; только node:crypto, zod и config/fragments.
+export { createCipher, DecryptError, generateSecret } from './cipher.js';

package/dist/database/batches.d.ts

@@ -0,0 +1,42 @@
+import type { SQL } from 'drizzle-orm';
+import { type Db } from './db.js';
+import type { PoolClient } from './pg.js';
+/** Опции `deleteInBatches`. */
+export interface KitDeleteInBatchesOptions {
+    /** `Db` сервиса: пачки — его транзакции, остановка `Db` прекращает новые пачки. */
+    readonly db: Db;
+    /**
+     * SQL пачки по её размеру; результат — одна строка с целой колонкой `deleted`, например
+     * `WITH d AS (DELETE … LIMIT n RETURNING 1) SELECT count(*)::int AS deleted FROM d` или вызов функции
+     * `SECURITY DEFINER` (строгий RLS скрывает строки компаний от системного контекста).
+     */
+    readonly sql: (batchSize: number) => SQL;
+    /** Размер пачки, целое ≥ 1. */
+    readonly batchSize: number;
+    /** Предел пачек за проход, целое ≥ 1. */
+    readonly maxBatches: number;
+    /** `false` — следующая пачка не начинается, текущая дорабатывает. */
+    readonly shouldContinue?: () => boolean;
+    /**
+     * Соединение для пачек — обычно соединение блокировки из `runExclusive(db, key, (connection) => …)`: второе
+     * соединение пула не берётся. Без него — транзакция `Db` на соединении основного пула. Транзакции `Db`
+     * (`db.transaction`, `db.read`) внутри `fn` `runExclusive` идут на других соединениях пула: на соединении
+     * блокировки работают только пачки этого вызова.
+     */
+    readonly connection?: PoolClient;
+}
+/** Итог прохода `deleteInBatches`. */
+export interface KitDeleteInBatchesResult {
+    /** Удалено строк. */
+    readonly deleted: number;
+    /** Выполнено пачек. */
+    readonly batches: number;
+    /** `true` — проход закончился неполной пачкой; `false` — остановлен maxBatches, shouldContinue или остановкой Db. */
+    readonly complete: boolean;
+}
+/**
+ * Удаление пачками: транзакция на пачку, до неполной пачки или `maxBatches` (AC-4.11). Остановка `Db` (шаг 3) ждёт
+ * текущую пачку, новая не начинается.
+ * @throws {RangeError} `batchSize` или `maxBatches` не целое ≥ 1.
+ */
+export declare function deleteInBatches(options: KitDeleteInBatchesOptions): Promise<KitDeleteInBatchesResult>;

package/dist/database/batches.js

@@ -0,0 +1,49 @@
+// deleteInBatches (prd.md §3.3, AC-4.11, UC-8, UC-9). Эталон — O batches.ts (выход при неполной пачке, maxBatches,
+// shouldContinue); I — отслеживание идущих пачек в Db. По PRD: пачка — Db.transaction с системным контекстом, SQL
+// возвращает одну строку с колонкой deleted.
+import { Logger } from '@nestjs/common';
+import { ulid } from '../internal/ids.js';
+import { isStopping, trackBatchRun, transactionOn } from './db.js';
+const logger = new Logger('deleteInBatches');
+function assertPositiveInt(value, name) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new RangeError(`deleteInBatches: ${name} — целое ≥ 1`);
+    }
+}
+function deletedOf(rows) {
+    const value = rows[0]?.deleted;
+    return typeof value === 'number' || typeof value === 'bigint' || typeof value === 'string'
+        ? Number(value)
+        : 0;
+}
+async function runBatches(options) {
+    const ctx = { tenant: null, traceId: ulid(), actor: { channel: 'system' } };
+    let deleted = 0;
+    let batches = 0;
+    while (batches < options.maxBatches &&
+        !isStopping(options.db) &&
+        (options.shouldContinue?.() ?? true)) {
+        const batch = (tx) => tx.execute(options.sql(options.batchSize));
+        const result = options.connection === undefined
+            ? await options.db.transaction(ctx, batch)
+            : await transactionOn(options.db, options.connection, ctx, batch);
+        const count = deletedOf(result.rows);
+        batches += 1;
+        deleted += count;
+        logger.debug({ batch: batches, deleted: count }, 'deleteInBatches: пачка');
+        if (count < options.batchSize) {
+            return { deleted, batches, complete: true };
+        }
+    }
+    return { deleted, batches, complete: false };
+}
+/**
+ * Удаление пачками: транзакция на пачку, до неполной пачки или `maxBatches` (AC-4.11). Остановка `Db` (шаг 3) ждёт
+ * текущую пачку, новая не начинается.
+ * @throws {RangeError} `batchSize` или `maxBatches` не целое ≥ 1.
+ */
+export function deleteInBatches(options) {
+    assertPositiveInt(options.batchSize, 'batchSize');
+    assertPositiveInt(options.maxBatches, 'maxBatches');
+    return trackBatchRun(options.db, runBatches(options));
+}

package/dist/database/db.d.ts

@@ -0,0 +1,93 @@
+import type { DrizzleDriver, NodePgDatabase, Pool, PoolClient } from './pg.js';
+import { type DbContext } from './tenant.js';
+/** Чтение через пул чтения (`readGlobal`): Drizzle node-postgres без транзакции. */
+export type DbReader = NodePgDatabase;
+/** Транзакция Drizzle node-postgres (`Db.transaction`, `Db.read`). */
+export type DbTx = Parameters<Parameters<NodePgDatabase['transaction']>[0]>[0];
+/** Задача после `COMMIT` (`Db.afterCommit`). */
+export type AfterCommitTask = () => void | Promise<void>;
+/** `Db.read` без тенанта: чтение без компании — только `Db.readGlobal` (строгий RLS, P0). */
+export declare class TenantRequiredError extends Error {
+    readonly name = "TenantRequiredError";
+    constructor();
+}
+/** `Db.afterCommit` в read-only транзакции или на `readGlobal`: задачи после `COMMIT` там невозможны. */
+export declare class AfterCommitInReadOnlyError extends Error {
+    readonly name = "AfterCommitInReadOnlyError";
+    constructor();
+}
+/**
+ * `Db.afterCommit` с дескриптором, который не является транзакцией этого `Db` (другой `Db`, `DRIZZLE`, вложенная
+ * `tx.transaction()`): задача никогда бы не выполнилась — ошибка вместо молчаливой потери.
+ */
+export declare class AfterCommitOutsideTransactionError extends Error {
+    readonly name = "AfterCommitOutsideTransactionError";
+    constructor();
+}
+/** Пулы и драйвер `Db`. */
+export interface DbOptions {
+    /** Основной пул (`transaction`, `runExclusive`). */
+    readonly main: Pool;
+    /** Пул чтения: `default_transaction_read_only`, `statement_timeout` 5 с (`read`, `readGlobal`). */
+    readonly read: Pool;
+    /** `drizzle()` из `loadDrizzle()`. */
+    readonly drizzle: DrizzleDriver['drizzle'];
+}
+/** Основной пул `Db` (для `runExclusive`). */
+export declare function mainPoolOf(db: Db): Pool;
+/**
+ * Транзакция `Db` (тенант, `afterCommit`) на уже выданном клиенте — например, на соединении блокировки `runExclusive`,
+ * без второго соединения пула (KT-22 п. 4). Клиент не возвращается в пул: им владеет вызывающий.
+ */
+export declare function transactionOn<T>(db: Db, client: PoolClient, ctx: DbContext, fn: (tx: DbTx) => Promise<T>): Promise<T>;
+/** Идёт остановка `Db` (шаг 3): новые пачки не начинаются. */
+export declare function isStopping(db: Db): boolean;
+/** Регистрирует проход пачек: `beforeApplicationShutdown` дожидается его. */
+export declare function trackBatchRun<T>(db: Db, run: Promise<T>): Promise<T>;
+/**
+ * Выделенный клиент пула на одну единицу работы; возвращается в пул всегда. Обрыв (событие `error` клиента или
+ * ошибка соединения из `work`) — `release(err)`: pg-pool уничтожает клиента, пул не исчерпывается (AC-4.4). drizzle-orm
+ * 0.45.4 выполняет BEGIN вне try/finally своей transaction() — поэтому клиент берётся здесь, а не Drizzle над пулом.
+ */
+export declare function withPoolClient<T>(pool: Pool, work: (client: PoolClient) => Promise<T>, onBroken?: (error: Error) => void): Promise<T>;
+/**
+ * Работа сервиса с БД под строгим RLS (§3.3): один `set_config('app.tenant', …, true)` на транзакцию, чтение без
+ * тенанта — только `readGlobal`, задачи после `COMMIT`, своя переменная `app.*`. Собирается `KitDatabaseModule`.
+ */
+export declare class Db {
+    private readonly logger;
+    private readonly afterCommitTasks;
+    private readonly transactions;
+    private readonly readOnly;
+    private readonly drizzle;
+    private readonly readPool;
+    private readonly reader;
+    /** @param options пулы (с учётом срока — KitDatabaseModule) и драйвер Drizzle. */
+    constructor(options: DbOptions);
+    /** Транзакция чтения и записи на основном пуле с тенантом `ctx.tenant` (`null` — строки компаний не видны). */
+    transaction<T>(ctx: DbContext, fn: (tx: DbTx) => Promise<T>): Promise<T>;
+    /**
+     * Read-only транзакция на пуле чтения (`statement_timeout` 5 с) с тенантом.
+     * @throws {TenantRequiredError} в `ctx` нет тенанта (до подключения).
+     */
+    read<T>(ctx: DbContext, fn: (tx: DbTx) => Promise<T>): Promise<T>;
+    /** Чтение без компании (глобальные таблицы): пул чтения без транзакции и без `set_config`. */
+    readGlobal<T>(fn: (db: DbReader) => Promise<T>): Promise<T>;
+    /**
+     * Задача после `COMMIT` транзакции `tx` — по порядку, до возврата результата `transaction`; при откате не
+     * выполняется; ошибка задачи — `error`-лог и GlitchTip, не пробрасывается. Только для того, что можно потерять.
+     * @throws {AfterCommitInReadOnlyError} `tx` — транзакция `read` или дескриптор `readGlobal`.
+     * @throws {AfterCommitOutsideTransactionError} `tx` — не транзакция этого `Db` (другой `Db`, вложенная).
+     */
+    afterCommit(tx: DbTx | DbReader, task: AfterCommitTask): void;
+    /**
+     * Переменная транзакции `app.*` (`set_config(name, value, true)`), имя и значение — параметрами (AC-4.16).
+     * Служебная `app.tenant` запрещена: тенант задаётся только `DbContext` в `transaction`/`read`.
+     * @throws {TypeError} имя вне `^app\.[a-z_]{1,48}$`, служебное имя пакета или `tx` — не транзакция `Db`.
+     */
+    setLocal(tx: DbTx | DbReader, name: string, value: string): Promise<void>;
+    /** Шаг 3 остановки: новые пачки `deleteInBatches` не начинаются, идущие дорабатывают. */
+    beforeApplicationShutdown(): Promise<void>;
+    private run;
+    private runAfterCommit;
+}