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

package/dist/idempotency/table.d.ts

@@ -0,0 +1,203 @@
+import { type PgSchema } from 'drizzle-orm/pg-core';
+/** Имя таблицы идемпотентности в схеме сервиса. */
+export declare const IDEMPOTENCY_TABLE = "idempotency_key";
+/** Имя функции очистки `SECURITY DEFINER` в схеме сервиса. */
+export declare const PURGE_FUNCTION = "idempotency_purge";
+/** Уникальное ограничение области и ключа (`ON CONFLICT ON CONSTRAINT`). */
+export declare const SCOPE_CONSTRAINT = "idempotency_key_scope_key";
+declare function defineTable(schema: PgSchema): import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "idempotency_key";
+    schema: string;
+    columns: {
+        tenant: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tenant";
+            tableName: "idempotency_key";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        subject: import("drizzle-orm/pg-core").PgColumn<{
+            name: "subject";
+            tableName: "idempotency_key";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        key: import("drizzle-orm/pg-core").PgColumn<{
+            name: "key";
+            tableName: "idempotency_key";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        fingerprint: import("drizzle-orm/pg-core").PgColumn<{
+            name: "fingerprint";
+            tableName: "idempotency_key";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        attempt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "attempt";
+            tableName: "idempotency_key";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        state: import("drizzle-orm/pg-core").PgColumn<{
+            name: "state";
+            tableName: "idempotency_key";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        responseStatus: import("drizzle-orm/pg-core").PgColumn<{
+            name: "response_status";
+            tableName: "idempotency_key";
+            dataType: "number";
+            columnType: "PgSmallInt";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        responseBody: import("drizzle-orm/pg-core").PgColumn<{
+            name: "response_body";
+            tableName: "idempotency_key";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        responseLocation: import("drizzle-orm/pg-core").PgColumn<{
+            name: "response_location";
+            tableName: "idempotency_key";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "idempotency_key";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+/** Таблица идемпотентности сервиса (`createIdempotencyTable`). */
+export type KitIdempotencyTable = ReturnType<typeof defineTable>;
+/**
+ * Таблица `idempotency_key` в схеме сервиса (§6): область (`tenant?`, `subject`), ключ, отпечаток запроса, метка
+ * попытки `attempt` (ответ пишет только захватившая строку попытка), состояние,
+ * сохранённый ответ (статус, тело, `Location`), время создания; RLS
+ * `tenant IS NOT DISTINCT FROM nullif(current_setting('app.tenant', true), '')`. SQL генерирует `drizzle-kit` сервиса;
+ * `FORCE ROW LEVEL SECURITY`, права `<svc>_app` и функцию очистки (`idempotencyPurgeSql`) — SQL-миграция сервиса.
+ */
+export declare function createIdempotencyTable(schema: PgSchema): KitIdempotencyTable;
+/**
+ * Текст SQL функции очистки `<схема>.idempotency_purge(batch integer)` для SQL-миграции сервиса (`drizzle-kit generate
+ * --custom`): `SECURITY DEFINER`, владелец `<схема>_directory`, `search_path`, `REVOKE ALL … FROM PUBLIC`,
+ * `GRANT EXECUTE … TO <схема>_app`; удаляет записи старше 24 ч пачкой. Без функции `KitIdempotencyModule` отказывает
+ * при старте. Операторы разделены `--> statement-breakpoint`.
+ * @throws {TypeError} имя схемы вне формата имени сервиса `^[a-z][a-z0-9-]{1,31}$`.
+ */
+export declare function idempotencyPurgeSql(schema: PgSchema): string;
+export {};

package/dist/idempotency/table.js

@@ -0,0 +1,86 @@
+// createIdempotencyTable, idempotencyPurgeSql (prd.md §3.3а v1.14, §6, AC-4.8, AC-4.14). Эталон — O idempotency.schema.ts,
+// 0002_functions.sql idempotency_purge. По PRD: tenant nullable, subject вместо actor, ответ с Location, политика
+// IS NOT DISTINCT FROM nullif(…). Файл без pg: его грузит drizzle-kit со схемой сервиса.
+import { sql } from 'drizzle-orm';
+import { check, index, jsonb, pgPolicy, smallint, text, timestamp, unique, uuid, } from 'drizzle-orm/pg-core';
+import { assertServiceName } from '../internal/service-name.js';
+import { quoteIdentifier } from '../internal/sql-identifier.js';
+/** Имя таблицы идемпотентности в схеме сервиса. */
+export const IDEMPOTENCY_TABLE = 'idempotency_key';
+/** Имя функции очистки `SECURITY DEFINER` в схеме сервиса. */
+export const PURGE_FUNCTION = 'idempotency_purge';
+/** Уникальное ограничение области и ключа (`ON CONFLICT ON CONSTRAINT`). */
+export const SCOPE_CONSTRAINT = 'idempotency_key_scope_key';
+/** Разделитель операторов миграций Drizzle. */
+const BREAKPOINT = '\n--> statement-breakpoint\n';
+function defineTable(schema) {
+    return schema.table(IDEMPOTENCY_TABLE, {
+        tenant: text('tenant'),
+        subject: text('subject').notNull(),
+        key: text('key').notNull(),
+        fingerprint: text('fingerprint').notNull(),
+        // Метка попытки, захватившей строку: ответ пишет только она (KT-22 п. 3).
+        attempt: uuid('attempt').notNull().defaultRandom(),
+        state: text('state').notNull().default('in_progress'),
+        responseStatus: smallint('response_status'),
+        responseBody: jsonb('response_body'),
+        responseLocation: text('response_location'),
+        createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    }, (t) => [
+        // PK по nullable-колонке невозможен: область и ключ — уникальное ограничение NULLS NOT DISTINCT (PG ≥ 15).
+        unique(SCOPE_CONSTRAINT).on(t.tenant, t.subject, t.key).nullsNotDistinct(),
+        index('idempotency_key_created_idx').on(t.createdAt),
+        check('idempotency_key_state_check', sql `${t.state} IN ('in_progress', 'done')`),
+        pgPolicy('idempotency_key_scope', {
+            as: 'permissive',
+            for: 'all',
+            to: 'public',
+            using: sql `${t.tenant} IS NOT DISTINCT FROM nullif(current_setting('app.tenant', true), '')`,
+            withCheck: sql `${t.tenant} IS NOT DISTINCT FROM nullif(current_setting('app.tenant', true), '')`,
+        }),
+    ]);
+}
+/**
+ * Таблица `idempotency_key` в схеме сервиса (§6): область (`tenant?`, `subject`), ключ, отпечаток запроса, метка
+ * попытки `attempt` (ответ пишет только захватившая строку попытка), состояние,
+ * сохранённый ответ (статус, тело, `Location`), время создания; RLS
+ * `tenant IS NOT DISTINCT FROM nullif(current_setting('app.tenant', true), '')`. SQL генерирует `drizzle-kit` сервиса;
+ * `FORCE ROW LEVEL SECURITY`, права `<svc>_app` и функцию очистки (`idempotencyPurgeSql`) — SQL-миграция сервиса.
+ */
+export function createIdempotencyTable(schema) {
+    return defineTable(schema);
+}
+/**
+ * Текст SQL функции очистки `<схема>.idempotency_purge(batch integer)` для SQL-миграции сервиса (`drizzle-kit generate
+ * --custom`): `SECURITY DEFINER`, владелец `<схема>_directory`, `search_path`, `REVOKE ALL … FROM PUBLIC`,
+ * `GRANT EXECUTE … TO <схема>_app`; удаляет записи старше 24 ч пачкой. Без функции `KitIdempotencyModule` отказывает
+ * при старте. Операторы разделены `--> statement-breakpoint`.
+ * @throws {TypeError} имя схемы вне формата имени сервиса `^[a-z][a-z0-9-]{1,31}$`.
+ */
+export function idempotencyPurgeSql(schema) {
+    const name = schema.schemaName;
+    assertServiceName(name, 'idempotencyPurgeSql');
+    const s = quoteIdentifier(name);
+    const table = `${s}.${quoteIdentifier(IDEMPOTENCY_TABLE)}`;
+    const fn = `${s}.${quoteIdentifier(PURGE_FUNCTION)}`;
+    const directory = quoteIdentifier(`${name}_directory`);
+    const app = quoteIdentifier(`${name}_app`);
+    return [
+        `CREATE OR REPLACE FUNCTION ${fn}(batch integer) RETURNS integer
+    LANGUAGE plpgsql VOLATILE SECURITY DEFINER SET search_path = ${s}, pg_temp AS $$
+DECLARE deleted integer;
+BEGIN
+    DELETE FROM ${table} i WHERE i.ctid IN (
+        SELECT o.ctid FROM ${table} o
+        WHERE o.created_at < now() - interval '24 hours' ORDER BY o.created_at LIMIT batch);
+    GET DIAGNOSTICS deleted = ROW_COUNT;
+    RETURN deleted;
+END $$;`,
+        `GRANT SELECT, DELETE ON ${table} TO ${directory};`,
+        `GRANT CREATE ON SCHEMA ${s} TO ${directory};`,
+        `ALTER FUNCTION ${fn}(integer) OWNER TO ${directory};`,
+        `REVOKE CREATE ON SCHEMA ${s} FROM ${directory};`,
+        `REVOKE ALL ON FUNCTION ${fn}(integer) FROM PUBLIC;`,
+        `GRANT EXECUTE ON FUNCTION ${fn}(integer) TO ${app};`,
+    ].join(BREAKPOINT);
+}

package/dist/internal/cleanup-result.d.ts

@@ -0,0 +1,7 @@
+/** Итог прохода — метка `result` метрики `verdeect_cleanup_runs_total` (без `error`). */
+export type CleanupResult = 'ok' | 'partial' | 'interrupted';
+/**
+ * `ok` — удалять больше нечего; `partial` — упёрся в `maxBatches`, записи старше срока остались; `interrupted` —
+ * остановлен (выкат), алерт `VerdeectCleanupFailing` его не учитывает.
+ */
+export declare function resultOf(complete: boolean, batches: number, maxBatches: number): CleanupResult;

package/dist/internal/cleanup-result.js

@@ -0,0 +1,12 @@
+// Итог прохода очистки (prd.md §3.3а, §3.4, AC-9.5; KT-22 п. 5): общий для очистки идемпотентности и сообщений —
+// messaging не импортирует idempotency (ARCHITECTURE). Перенос resultOf из kit-idempotency.module.ts (E4).
+/**
+ * `ok` — удалять больше нечего; `partial` — упёрся в `maxBatches`, записи старше срока остались; `interrupted` —
+ * остановлен (выкат), алерт `VerdeectCleanupFailing` его не учитывает.
+ */
+export function resultOf(complete, batches, maxBatches) {
+    if (complete) {
+        return 'ok';
+    }
+    return batches === maxBatches ? 'partial' : 'interrupted';
+}

package/dist/internal/ids.d.ts

@@ -0,0 +1,13 @@
+/** Формат префикса идентификатора `newId`: 2–5 строчных латинских букв (реестр префиксов — README). */
+export declare const ID_PREFIX: RegExp;
+/**
+ * ULID: 10 знаков времени (`now`, мс, по умолчанию `Date.now()`) и 16 случайных знаков Crockford base32.
+ * Сортировка строк совпадает с порядком по времени до миллисекунды.
+ * @throws {RangeError} `now` не целое, отрицательное или больше 2^48 − 1.
+ */
+export declare function ulid(now?: number): string;
+/**
+ * Идентификатор сущности `<prefix>_<ULID>`, например `fil_01J…` (AC-4.9).
+ * @throws {TypeError} префикс вне формата `^[a-z]{2,5}$`.
+ */
+export declare function newId(prefix: string): string;

package/dist/internal/ids.js

@@ -0,0 +1,41 @@
+// ulid, newId (prd.md §3.3, AC-4.9). Эталон — O ids.ts: алфавит Crockford, 10 знаков времени, 16 случайных;
+// по PRD — проверка префикса ^[a-z]{2,5}$, без монотонности внутри миллисекунды.
+import { randomBytes } from 'node:crypto';
+/** Алфавит Crockford base32 (без I, L, O, U). */
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/** Наибольшее время ULID — 48 бит миллисекунд. */
+const MAX_TIME = 2 ** 48 - 1;
+/** Формат префикса идентификатора `newId`: 2–5 строчных латинских букв (реестр префиксов — README). */
+export const ID_PREFIX = /^[a-z]{2,5}$/;
+/**
+ * ULID: 10 знаков времени (`now`, мс, по умолчанию `Date.now()`) и 16 случайных знаков Crockford base32.
+ * Сортировка строк совпадает с порядком по времени до миллисекунды.
+ * @throws {RangeError} `now` не целое, отрицательное или больше 2^48 − 1.
+ */
+export function ulid(now = Date.now()) {
+    if (!Number.isInteger(now) || now < 0 || now > MAX_TIME) {
+        throw new RangeError('ulid: время вне диапазона');
+    }
+    let time = '';
+    let rest = now;
+    for (let index = 0; index < 10; index += 1) {
+        time = CROCKFORD.charAt(rest % 32) + time;
+        rest = Math.floor(rest / 32);
+    }
+    let random = '';
+    // 256 делится на 32 без остатка — взятие по модулю не смещает распределение (O).
+    for (const byte of randomBytes(16)) {
+        random += CROCKFORD.charAt(byte % 32);
+    }
+    return time + random;
+}
+/**
+ * Идентификатор сущности `<prefix>_<ULID>`, например `fil_01J…` (AC-4.9).
+ * @throws {TypeError} префикс вне формата `^[a-z]{2,5}$`.
+ */
+export function newId(prefix) {
+    if (!ID_PREFIX.test(prefix)) {
+        throw new TypeError(`newId: префикс «${prefix}» вне формата ^[a-z]{2,5}$`);
+    }
+    return `${prefix}_${ulid()}`;
+}

package/dist/internal/metadata.d.ts

@@ -0,0 +1,12 @@
+/** Ключ метаданных `@Idempotent` на методе обработчика; значение — `KitIdempotentOptions`. */
+export declare const IDEMPOTENT_METADATA = "verdeect-kit:idempotent";
+/** Опции `@Idempotent` (prd.md §3.3а). */
+export interface KitIdempotentOptions {
+    /** Ключ `Idempotency-Key` обязателен: без него — 400 `IDEMPOTENCY_KEY_REQUIRED`. По умолчанию `false`. */
+    readonly required?: boolean;
+    /**
+     * Путь поля тела через точку, из которого берётся тенант области для служебного принципала
+     * (`service`); у пользователя и агента тенант — только из принципала, поле игнорируется.
+     */
+    readonly tenantFromBody?: string;
+}

package/dist/internal/metadata.js

@@ -0,0 +1,3 @@
+// Ключи метаданных декораторов: Idempotent → @Api без цикла http ↔ idempotency (ARCHITECTURE.md; prd.md §3.3а, §3.5).
+/** Ключ метаданных `@Idempotent` на методе обработчика; значение — `KitIdempotentOptions`. */
+export const IDEMPOTENT_METADATA = 'verdeect-kit:idempotent';

package/dist/internal/outbox-policy.d.ts

@@ -0,0 +1,8 @@
+/** Таблица outbox в схеме сервиса. */
+export declare const OUTBOX_TABLE = "outbox";
+/** Таблица inbox в схеме сервиса. */
+export declare const INBOX_TABLE = "inbox";
+/** Политика outbox. */
+export declare const OUTBOX_POLICY = "outbox_tenant_isolation";
+/** Исключение строгой модели (§3.4, §6): пустой тенант — все строки (relay, очистка); иначе — только строки тенанта. */
+export declare const OUTBOX_POLICY_SQL = "coalesce(current_setting('app.tenant', true), '') = '' OR tenant = current_setting('app.tenant', true)";

package/dist/internal/outbox-policy.js

@@ -0,0 +1,10 @@
+// Имена таблиц сообщений и политика outbox (prd.md §3.4, §6, AC-4.8): общие для /messaging и /testing
+// (assertStrictTenantIsolation, expectOutbox) — /testing не грузит /messaging (без amqplib).
+/** Таблица outbox в схеме сервиса. */
+export const OUTBOX_TABLE = 'outbox';
+/** Таблица inbox в схеме сервиса. */
+export const INBOX_TABLE = 'inbox';
+/** Политика outbox. */
+export const OUTBOX_POLICY = 'outbox_tenant_isolation';
+/** Исключение строгой модели (§3.4, §6): пустой тенант — все строки (relay, очистка); иначе — только строки тенанта. */
+export const OUTBOX_POLICY_SQL = "coalesce(current_setting('app.tenant', true), '') = '' OR tenant = current_setting('app.tenant', true)";

package/dist/internal/peer.d.ts

@@ -0,0 +1,16 @@
+type Importer = (specifier: string) => Promise<unknown>;
+/** Текст ошибки AC-1.2. */
+export declare function missingPeerMessage(library: string, subpath: string): string;
+/** Загружает peer через importer; отсутствие самого пакета → ошибка AC-1.2, прочее — как есть. */
+export declare function loadPeerWith<T>(importer: Importer, library: string, subpath: string): Promise<T>;
+/** Опциональный peer подпути; вызывается top-level await в модуле подпути. */
+export declare function loadPeer<T>(library: string, subpath: string): Promise<T>;
+type Resolver = (specifier: string) => string;
+/** Синхронная проверка peer через resolver; отсутствие самого пакета → ошибка AC-1.2, прочее — как есть. */
+export declare function requirePeerWith(resolver: Resolver, library: string, subpath: string): void;
+/**
+ * Синхронная проверка, что peer установлен (без загрузки); вызывается на верхнем уровне модуля подпути без
+ * top-level await. Сам peer загружается потом ленивым `import()`.
+ */
+export declare function requirePeer(library: string, subpath: string): void;
+export {};

package/dist/internal/peer.js

@@ -0,0 +1,56 @@
+// Загрузка опционального peer с текстом ошибки AC-1.2 (prd.md §3, NFR-3; ARCHITECTURE.md «Правила зависимостей»).
+// Вызывается top-level await в модуле подпути: статический импорт отсутствующего пакета упал бы при связывании ESM
+// с ERR_MODULE_NOT_FOUND до любого кода. requirePeer — синхронная проверка при загрузке модуля подпути без top-level
+// await (/database, /idempotency: drizzle-kit загружает схему сервиса через require — П15, KT-20 п. 2).
+import { createRequire } from 'node:module';
+/** Текст ошибки AC-1.2. */
+export function missingPeerMessage(library, subpath) {
+    return `@verdeect/kit/${subpath} требует ${library} — добавьте в зависимости сервиса`;
+}
+/** Не найден сам пакет library; отсутствующая вложенная зависимость peer называет другой пакет. */
+function isMissingPackage(error, library) {
+    if (typeof error !== 'object' || error === null || !('code' in error)) {
+        return false;
+    }
+    if (error.code !== 'ERR_MODULE_NOT_FOUND' && error.code !== 'MODULE_NOT_FOUND') {
+        return false;
+    }
+    const message = 'message' in error ? String(error.message) : '';
+    return message.includes(`'${library}'`) || message.includes(`"${library}"`);
+}
+/** Загружает peer через importer; отсутствие самого пакета → ошибка AC-1.2, прочее — как есть. */
+export async function loadPeerWith(importer, library, subpath) {
+    try {
+        return (await importer(library));
+    }
+    catch (error) {
+        if (isMissingPackage(error, library)) {
+            throw new Error(missingPeerMessage(library, subpath), { cause: error });
+        }
+        throw error;
+    }
+}
+/** Опциональный peer подпути; вызывается top-level await в модуле подпути. */
+export function loadPeer(library, subpath) {
+    return loadPeerWith((specifier) => import(specifier), library, subpath);
+}
+/** Синхронная проверка peer через resolver; отсутствие самого пакета → ошибка AC-1.2, прочее — как есть. */
+export function requirePeerWith(resolver, library, subpath) {
+    try {
+        resolver(library);
+    }
+    catch (error) {
+        if (isMissingPackage(error, library)) {
+            throw new Error(missingPeerMessage(library, subpath), { cause: error });
+        }
+        throw error;
+    }
+}
+/**
+ * Синхронная проверка, что peer установлен (без загрузки); вызывается на верхнем уровне модуля подпути без
+ * top-level await. Сам peer загружается потом ленивым `import()`.
+ */
+export function requirePeer(library, subpath) {
+    const require = createRequire(import.meta.url);
+    requirePeerWith((specifier) => require.resolve(specifier), library, subpath);
+}

package/dist/internal/pg-errors.d.ts

@@ -0,0 +1,21 @@
+/** Нарушение уникальности (23505); `constraint` — имя ограничения первого такого узла цепочки. */
+export declare function isUniqueViolation(error: unknown, constraint?: string): boolean;
+/**
+ * Ошибка соединения с PostgreSQL: SQLSTATE `08xxx`, `57P01`–`57P03`, системные коды обрыва сети, сообщения pg
+ * «Connection terminated…», «terminating connection…» и «Client has encountered a connection error…» — в ошибке или
+ * её `cause`.
+ */
+export declare function isConnectionError(error: unknown): boolean;
+/** Срок ожидания клиента пула истёк (тексты pg-pool) — в ошибке или её `cause`, в том числе внутри `DomainError`. */
+export declare function isPoolTimeout(error: unknown): boolean;
+/** Имя пула `/database`: основной или пул чтения (метка `pool` метрики срока, AC-4.5). */
+export type KitPoolName = 'main' | 'read';
+/**
+ * Помечает узел срока пула в цепочке `cause` именем пула. `true` — метка поставлена сейчас (вызывающий
+ * учитывает срок один раз); `false` — узла срока нет или он уже помечен.
+ */
+export declare function tagPoolTimeout(error: unknown, pool: KitPoolName): boolean;
+/** Имя пула из метки `tagPoolTimeout` первого помеченного узла цепочки или `null`. */
+export declare function poolTimeoutOf(error: unknown): KitPoolName | null;
+/** SQLSTATE первого узла цепочки `cause` (до 10 уровней) или `null` — например, ошибка pg в `cause` `DrizzleQueryError`. */
+export declare function sqlStateOf(error: unknown): string | null;

package/dist/internal/pg-errors.js

@@ -0,0 +1,115 @@
+// isUniqueViolation, isConnectionError, isPoolTimeout — по форме объекта, обход cause, без pg и drizzle-orm (prd.md §3.3;
+// rules/base.md). Эталоны: isUniqueViolation — I pg-errors.ts; isPoolTimeout — O pool-client.ts (сообщения);
+// isConnectionError — по PRD (у I/O — instanceof DrizzleQueryError, не переносится; формы — KT-15 п. 9).
+// tagPoolTimeout/poolTimeoutOf — метка пула /database: срок учтён (решение E3, KT-19 п. 3, AC-4.5).
+/** Глубина обхода `cause` — как у `sanitizeError` (§3.2). */
+const MAX_CAUSE_DEPTH = 10;
+/** SQLSTATE нарушения уникальности (PostgreSQL, класс 23). */
+const UNIQUE_VIOLATION = '23505';
+/** Тексты pg-pool при истечении срока ожидания клиента (O pool-client.ts POOL_TIMEOUT_MESSAGES). */
+const POOL_TIMEOUT_MESSAGES = new Set([
+    'timeout exceeded when trying to connect',
+    'Connection terminated due to connection timeout',
+]);
+/** SQLSTATE прекращения работы сервера: admin_shutdown, crash_shutdown, cannot_connect_now (класс 57P). */
+const SHUTDOWN_SQLSTATES = new Set(['57P01', '57P02', '57P03']);
+/** Системные коды Node обрыва и отказа сети. */
+const NETWORK_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'EPIPE',
+    'ENOTFOUND',
+]);
+/** Начала сообщений pg при обрыве соединения (последнее — запрос на клиенте после обрыва, AC-4.10). */
+const CONNECTION_MESSAGE_PREFIXES = [
+    'Connection terminated',
+    'terminating connection',
+    'Client has encountered a connection error',
+];
+/** Ошибка и её `cause` до 10 уровней: только объекты, цикл не зацикливает. */
+function causeChain(error) {
+    const chain = [];
+    const seen = new Set();
+    let current = error;
+    while (chain.length < MAX_CAUSE_DEPTH &&
+        typeof current === 'object' &&
+        current !== null &&
+        !seen.has(current)) {
+        seen.add(current);
+        chain.push(current);
+        current = current.cause;
+    }
+    return chain;
+}
+/** Нарушение уникальности (23505); `constraint` — имя ограничения первого такого узла цепочки. */
+export function isUniqueViolation(error, constraint) {
+    const node = causeChain(error).find((item) => item.code === UNIQUE_VIOLATION);
+    if (node === undefined) {
+        return false;
+    }
+    return constraint === undefined || node.constraint === constraint;
+}
+function isConnectionNode(node) {
+    if (typeof node.code === 'string') {
+        if (node.code.startsWith('08') && node.code.length === 5) {
+            return true;
+        }
+        if (SHUTDOWN_SQLSTATES.has(node.code) || NETWORK_CODES.has(node.code)) {
+            return true;
+        }
+    }
+    const message = node.message;
+    return (typeof message === 'string' &&
+        CONNECTION_MESSAGE_PREFIXES.some((prefix) => message.startsWith(prefix)));
+}
+/**
+ * Ошибка соединения с PostgreSQL: SQLSTATE `08xxx`, `57P01`–`57P03`, системные коды обрыва сети, сообщения pg
+ * «Connection terminated…», «terminating connection…» и «Client has encountered a connection error…» — в ошибке или
+ * её `cause`.
+ */
+export function isConnectionError(error) {
+    return causeChain(error).some(isConnectionNode);
+}
+/** Срок ожидания клиента пула истёк (тексты pg-pool) — в ошибке или её `cause`, в том числе внутри `DomainError`. */
+export function isPoolTimeout(error) {
+    return causeChain(error).some(isPoolTimeoutNode);
+}
+/** Неперечисляемая метка «срок учтён пулом» на узле ошибки срока. */
+const POOL_TAG = Symbol.for('verdeect-kit.pool');
+function isPoolTimeoutNode(node) {
+    return typeof node.message === 'string' && POOL_TIMEOUT_MESSAGES.has(node.message);
+}
+/**
+ * Помечает узел срока пула в цепочке `cause` именем пула. `true` — метка поставлена сейчас (вызывающий
+ * учитывает срок один раз); `false` — узла срока нет или он уже помечен.
+ */
+export function tagPoolTimeout(error, pool) {
+    const node = causeChain(error).find(isPoolTimeoutNode);
+    if (node === undefined || Object.prototype.hasOwnProperty.call(node, POOL_TAG)) {
+        return false;
+    }
+    Object.defineProperty(node, POOL_TAG, { value: pool, enumerable: false });
+    return true;
+}
+/** Имя пула из метки `tagPoolTimeout` первого помеченного узла цепочки или `null`. */
+export function poolTimeoutOf(error) {
+    for (const node of causeChain(error)) {
+        const tag = node[POOL_TAG];
+        if (tag === 'main' || tag === 'read') {
+            return tag;
+        }
+    }
+    return null;
+}
+/** SQLSTATE: 5 знаков `0-9A-Z` с цифрой (системные коды Node вроде `EPIPE` цифр не содержат). */
+const SQLSTATE = /^(?=.*\d)[0-9A-Z]{5}$/;
+/** SQLSTATE первого узла цепочки `cause` (до 10 уровней) или `null` — например, ошибка pg в `cause` `DrizzleQueryError`. */
+export function sqlStateOf(error) {
+    for (const node of causeChain(error)) {
+        if (typeof node.code === 'string' && SQLSTATE.test(node.code)) {
+            return node.code;
+        }
+    }
+    return null;
+}

package/dist/internal/preparsed-env.d.ts

@@ -0,0 +1,4 @@
+/** Запоминает разобранное окружение схемы (пишет bootstrapService). */
+export declare function setPreparsedEnv(schema: object, env: Record<string, unknown>): void;
+/** Возвращает и удаляет разобранное окружение схемы; нет — `undefined`. */
+export declare function takePreparsedEnv(schema: object): Record<string, unknown> | undefined;

package/dist/internal/preparsed-env.js

@@ -0,0 +1,14 @@
+// Окружение, разобранное bootstrapService до создания приложения (prd.md §3.1, §3.5, AC-3.13). KitConfigModule забирает
+// его при сборке контекста и не разбирает повторно. Ключ — объект схемы: тот же env в bootstrapService({env}) и
+// KitConfigModule.forRoot({schema}). Значение отдаётся одной сборке: следующая разбирает process.env сама (AC-1.7).
+const preparsed = new WeakMap();
+/** Запоминает разобранное окружение схемы (пишет bootstrapService). */
+export function setPreparsedEnv(schema, env) {
+    preparsed.set(schema, env);
+}
+/** Возвращает и удаляет разобранное окружение схемы; нет — `undefined`. */
+export function takePreparsedEnv(schema) {
+    const env = preparsed.get(schema);
+    preparsed.delete(schema);
+    return env;
+}