letopis 0.20.3 → 1.0.0

package/dist/sync.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Синхронизация моделей с базой и генерация типов (план, этап 2, п. 7).
+ *
+ * syncModels: описания моделей сравниваются со строками Class арендатора сессии; все изменения
+ * выполняются одной транзакцией. Сухой прогон откатывает её в конце, поэтому ужесточение с
+ * мешающими строками отклоняет сама база (`tightening_conflict` с перечнем) уже в сухом прогоне.
+ * generateTypes: объявления TypeScript для классов из реестра — в том числе созданных данными.
+ */
+import type { Db } from './index.js';
+import type { AnyModel, LostRule } from './model.js';
+import type { JsonSchema } from './jsonschema.js';
+import type { Registry } from './registry.js';
+export interface SyncResult {
+    applied: boolean;
+    created: string[];
+    updated: string[];
+    unchanged: string[];
+    /** Классы системного арендатора: их меняет только установка. */
+    skipped: string[];
+    /** Правила refine, которых нет в базе. */
+    lost: LostRule[];
+}
+export declare function syncModels(db: Db, models: readonly AnyModel[], opts?: {
+    apply?: boolean;
+}): Promise<SyncResult>;
+/** Тип TypeScript по JSON Schema подмножества. */
+export declare function schemaToTs(s: JsonSchema | undefined, indent?: string): string;
+/** Объявления `<Класс>Data` и `<Класс>Links` для классов реестра (кроме системных). */
+export declare function generateTypes(registry: Registry, opts?: {
+    includeSystem?: boolean;
+}): string;

package/dist/sync.js

@@ -0,0 +1,108 @@
+import { LetopisError } from './errors.js';
+const ROLLBACK = Symbol('sync-dry-run');
+/** Канонический JSON: ключи по алфавиту — сравнение описаний без учёта порядка ключей. */
+function canon(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canon).join(',')}]`;
+    if (v && typeof v === 'object')
+        return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canon(v[k])}`).join(',')}}`;
+    return JSON.stringify(v);
+}
+export async function syncModels(db, models, opts = {}) {
+    const res = { applied: Boolean(opts.apply), created: [], updated: [], unchanged: [], skipped: [], lost: models.flatMap((m) => m.lostRules()) };
+    const S = `"${db.schema.replace(/"/g, '""')}"`;
+    // предок раньше потомка
+    const ordered = [];
+    const visit = (m) => {
+        if (ordered.includes(m))
+            return;
+        if (m.parent && models.includes(m.parent))
+            visit(m.parent);
+        ordered.push(m);
+    };
+    models.forEach(visit);
+    try {
+        await db.transaction(async (tx) => {
+            for (const m of ordered) {
+                const desc = m.describe();
+                const [cur] = await tx.unsafe(`select tenant = ${S}.ctx_tenant() as own, data - 'resolved' as data from ${S}.entity
+          where class = 'Class' and data->>'name' = $1 and tenant in (${S}.ctx_tenant(), '2eba6d0a-1edd-4bb6-a85a-a703dab49035')`, [m.name]);
+                if (cur && !cur.own) {
+                    res.skipped.push(m.name);
+                }
+                else if (!cur) {
+                    await tx.unsafe(`insert into ${S}.entity (class, data) values ('Class', $1::jsonb)`, [desc]);
+                    res.created.push(m.name);
+                }
+                else if (canon(cur.data) === canon(desc)) {
+                    res.unchanged.push(m.name);
+                }
+                else {
+                    await tx.unsafe(`update ${S}.entity set data = $2::jsonb where class = 'Class' and tenant = ${S}.ctx_tenant() and data->>'name' = $1`, [m.name, desc]);
+                    res.updated.push(m.name);
+                }
+            }
+            if (!opts.apply)
+                throw ROLLBACK;
+        });
+    }
+    catch (e) {
+        if (e !== ROLLBACK)
+            throw e;
+    }
+    if (opts.apply)
+        await db.refresh();
+    return res;
+}
+/** Тип TypeScript по JSON Schema подмножества. */
+export function schemaToTs(s, indent = '') {
+    if (!s || Object.keys(s).length === 0)
+        return 'unknown';
+    if (s.const !== undefined)
+        return JSON.stringify(s.const);
+    if (Array.isArray(s.enum))
+        return s.enum.map((v) => JSON.stringify(v)).join(' | ');
+    if (Array.isArray(s.anyOf) || Array.isArray(s.oneOf))
+        return (s.anyOf ?? s.oneOf).map((b) => schemaToTs(b, indent)).join(' | ');
+    const types = Array.isArray(s.type) ? s.type : [s.type];
+    return types.map((t) => {
+        switch (t) {
+            case 'string': return 'string';
+            case 'integer':
+            case 'number': return 'number';
+            case 'boolean': return 'boolean';
+            case 'null': return 'null';
+            case 'array': return `Array<${schemaToTs(s.items, indent)}>`;
+            case 'object': {
+                const props = (s.properties ?? {});
+                const req = new Set((s.required ?? []));
+                const inner = indent + '  ';
+                const lines = Object.entries(props).map(([k, v]) => `${inner}${JSON.stringify(k)}${req.has(k) ? '' : '?'}: ${schemaToTs(v, inner)};`);
+                if (s.additionalProperties && typeof s.additionalProperties === 'object') {
+                    const key = s.propertyNames && Array.isArray(s.propertyNames.enum) ? s.propertyNames.enum.map((x) => JSON.stringify(x)).join(' | ') : 'string';
+                    const rec = `Partial<Record<${key}, ${schemaToTs(s.additionalProperties, inner)}>>`;
+                    return lines.length ? `{\n${lines.join('\n')}\n${indent}} & ${rec}` : rec;
+                }
+                return lines.length ? `{\n${lines.join('\n')}\n${indent}}` : 'Record<string, unknown>';
+            }
+            default: return 'unknown';
+        }
+    }).join(' | ');
+}
+/** Объявления `<Класс>Data` и `<Класс>Links` для классов реестра (кроме системных). */
+export function generateTypes(registry, opts = {}) {
+    const out = ['// Сгенерировано letopis types — не править руками.', ''];
+    for (const c of registry.all().sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!opts.includeSystem && c.tenant === '2eba6d0a-1edd-4bb6-a85a-a703dab49035')
+            continue;
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(c.name))
+            throw new LetopisError('invalid_class', `types: имя класса ${c.name} не годится для идентификатора TypeScript`);
+        // additionalProperties: false верхнего уровня в тип не переносится — лишние ключи и так ошибка типов
+        const { additionalProperties: _closed, ...open } = c.schema;
+        void _closed;
+        out.push(`export interface ${c.name}Data ${schemaToTs(open)}`);
+        const ends = Object.entries(c.ends).map(([role, e]) => `  ${JSON.stringify(role)}${e.required || (e.min ?? 0) > 0 ? '' : '?'}: ${e.many ? 'string[]' : 'string'};`);
+        out.push(`export interface ${c.name}Links {${ends.length ? `\n${ends.join('\n')}\n` : ''}}`, '');
+    }
+    return out.join('\n');
+}

package/dist/tx.d.ts

@@ -1,13 +1,134 @@
 /**
- * Транзакции: db.begin() → tr (тот же API на выделенном соединении),
- * db.commit(tr) / db.rollback(tr) / tr.commit() / tr.rollback().
- * tr.lock(...) — pg_advisory_xact_lock (сериализация гонок, напр. двойная бронь).
+ * Клиентский контекст (план, §2.5, §2.9, этап 2, п. 5; этап 4, п. 9; этап 5): каждая операция
+ * библиотеки — транзакция `read committed`, первые операторы которой выставляют `letopis.token` (и при
+ * необходимости `letopis.account`, `letopis.tenant`, `letopis.reason`) через set_config(…, true) —
+ * настройки живут до конца транзакции, соединение в пуле чужой токен не унесёт.
+ *
+ * Пропуск прав (`letopis.acl`, этап 5): подписанный базой план прав актора. Без него база считает
+ * план на каждый запрос (сотни микросекунд); с ним — проверяет подпись. Пропуск кэшируется на
+ * подключение по токену, актору и арендатору; нет пропуска — первая же операция берёт его тем же
+ * конвейером. Устаревший пропуск база не принимает и считает план сама — кэш влияет на скорость,
+ * а не на права; библиотека сбрасывает его по сигналам изменений прав и через минуту.
+ *
+ * Исполнитель (Executor) — общий вход цепочек: операция из пула — отдельная транзакция с повтором
+ * при 40P01, 40001 и конфликте журнала (план повторяется целиком); явная транзакция db.begin() —
+ * одно зарезервированное соединение, повторы — дело приложения. Любая ошибка внутри явной
+ * транзакции её ломает: rollback() проходит, commit() откатывает, возвращает соединение и бросает
+ * исходную ошибку — при каждом вызове. Обрыв связи во время COMMIT — commit_unknown, без повтора.
+ *
+ * Сигналы (решение 9 точки А): транзакции библиотеки помечены `letopis.notify = 'deferred'` —
+ * триггер не шлёт NOTIFY, а копит имена изменённых классов в `letopis.changed`; после фиксации
+ * их забирает нотификатор процесса и раз в интервал (по умолчанию 100 мс) отправляет одной
+ * транзакцией без данных: такая фиксация не ждёт диск и не задерживает чужие записи.
  */
-import { type Ctx } from './sql.js';
-export interface TxCtx extends Ctx {
+import type postgres from 'postgres';
+type Sql = postgres.Sql<Record<string, unknown>>;
+export type Tx = postgres.TransactionSql<Record<string, unknown>>;
+/** Транзиентные ошибки PG, которые снимает повтор: взаимная блокировка, сериализация. */
+export declare function isTransient(e: unknown): boolean;
+/** Конфликт пары «id, номер версии» в журнале — параллельные удаление и создание одного id (§2.5). */
+export declare function isLogConflict(e: unknown): boolean;
+/** Обрыв связи: сокет закрыт или серверный процесс завершён (FATAL) — исход отправленного неизвестен. */
+export declare function isConnectionError(e: unknown): boolean;
+export declare const RETRIES = 3;
+export declare const retryDelay: (attempt: number) => Promise<void>;
+/** Нотификатор процесса: копит имена классов и отправляет их пачкой раз в интервал. */
+export declare class Notifier {
+    private sql;
+    private channel;
+    private intervalMs;
+    private onError;
+    private queue;
+    private timer;
+    private stopped;
+    private flushing;
+    constructor(sql: Sql, channel: string, intervalMs: number, onError?: (e: unknown) => void);
+    /** Добавить классы из letopis.changed (строка через запятую). */
+    add(changed: string | null | undefined): void;
+    /** Отправить накопленное сейчас (вызывается по таймеру и при закрытии). */
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+/** Кэш подписанных пропусков прав одного подключения: по токену, актору и арендатору. */
+export declare class AclPasses {
+    readonly schema: string;
+    private ttlMs;
+    private max;
+    private map;
+    /** schema — имя схемы в кавычках (для вызова acl_token). */
+    constructor(schema: string, ttlMs?: number, max?: number);
+    private key;
+    get(c: TxContext): string | null;
+    set(c: TxContext, pass: string | null | undefined): void;
+    /** Права изменились (сигнал строк прав, auth.switch): все пропуска — заново. */
+    clear(): void;
+}
+export interface TxContext {
+    sql: Sql;
+    token: string | null;
+    notifier: Notifier | null;
+    /** Имперсонация: аккаунт, от имени которого действует сервис (letopis.account, этап 5). */
+    account?: string;
+    /** Рабочий арендатор (letopis.tenant): собственный или по членству; база проверяет членство. */
+    tenant?: string;
+    reason?: string;
+    /** Кэш пропусков прав подключения (letopis.acl). */
+    passes?: AclPasses;
+    /** После успешной операции (продление сессии раз в минуту). */
+    after?: () => void;
+    /**
+     * После фиксации записи: имена из letopis.changed (классы, session:<тег>) — кэш результатов
+     * сбрасывает свои ответы сразу (§2.12); raw — запись через db.sql.
+     */
+    onChanged?: (names: string[], raw: boolean) => void;
+}
+/**
+ * Операция одной транзакцией с контекстом сессии и повтором при транзиентных ошибках и конфликте
+ * журнала. Ошибки базы переводятся в LetopisError. read — операция только читает: сигналы не собираются.
+ */
+export declare function runTx<T>(ctx: TxContext, fn: (tx: Tx) => Promise<T>, opts?: {
+    retries?: number;
+    read?: boolean;
+    raw?: boolean;
+}): Promise<T>;
+/** Вход цепочек: где исполнить операцию — отдельной транзакцией из пула или в явной транзакции. */
+export interface Executor {
+    /** Операция одной транзакцией; в явной транзакции — в ней, без повторов. raw — сырой SQL (db.sql). */
+    run<T>(fn: (tx: Tx) => Promise<T>, opts?: {
+        read?: boolean;
+        raw?: boolean;
+    }): Promise<T>;
+    /** Внутри db.begin(). */
+    readonly explicit: boolean;
+}
+/** Исполнитель пула: каждая операция — своя транзакция с повторами. */
+export declare function poolExecutor(ctx: TxContext): Executor;
+/**
+ * Явная транзакция db.begin() (этап 4, п. 9): одно зарезервированное соединение, read committed.
+ * Ошибка любого запроса ломает транзакцию (правило §2.5): дальше каждый вызов бросает исходную
+ * ошибку, rollback() проходит, commit() откатывает и бросает её же. Ответ ROLLBACK на COMMIT
+ * (PostgreSQL так фиксирует сломанную транзакцию) — тоже ошибка.
+ */
+export declare class ExplicitTx implements Executor {
+    private ctx;
+    private conn;
+    readonly explicit = true;
+    private broken;
+    private done;
+    private failure;
+    /** В транзакции был сырой SQL (db.sql): после фиксации — весь кэш. */
+    private raw;
+    private constructor();
+    static open(ctx: TxContext): Promise<ExplicitTx>;
+    /** Транзакция ещё открыта (не зафиксирована и не откачена). */
+    get active(): boolean;
+    run<T>(fn: (tx: Tx) => Promise<T>, opts?: {
+        read?: boolean;
+        raw?: boolean;
+    }): Promise<T>;
+    /** Advisory-блокировка до конца транзакции (отдельное от блокировок семейств пространство ключей). */
+    lock(...keys: (string | number)[]): Promise<void>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
 }
-export declare function beginTx(ctx: Ctx): Promise<TxCtx>;
-/** Advisory-lock на составной ключ; живёт до конца транзакции. */
-export declare function lock(ctx: Ctx, ...keys: (string | number)[]): Promise<void>;
+export {};