letopis 1.4.1 → 2.0.0

package/dist/sync.js

@@ -1,4 +1,6 @@
-import { LetopisError } from './errors.js';
+import { lerr, lmsg } from './errors.js';
+import { internalsOf } from './internal.js';
+import { RESERVED_CLASS_NAMES } from './types.js';
 const ROLLBACK = Symbol('sync-dry-run');
 /** Канонический JSON: ключи по алфавиту — сравнение описаний без учёта порядка ключей. */
 function canon(v) {
@@ -9,11 +11,17 @@ function canon(v) {
     return JSON.stringify(v);
 }
 export async function syncModels(db, models, opts = {}) {
+    // хаб с именем метода цепочки или корня db (модель собрана мимо hub()) — отказ до записи (план 2.0, этап 4, п. 2;
+    // 7.10 №3); связь с таким именем отклоняет база
+    for (const m of models) {
+        if (m.kind === 'hub' && RESERVED_CLASS_NAMES.includes(m.name))
+            throw lerr('model.sync_hub_name_reserved', { name: m.name });
+    }
     const res = { applied: Boolean(opts.apply), created: [], updated: [], unchanged: [], skipped: [], lost: models.flatMap((m) => m.lostRules()) };
     const S = `"${db.schema.replace(/"/g, '""')}"`;
-    // предок раньше потомка; класс-источник агрегата раньше цели: агрегат над классом, которого ещё нет, база отклоняет.
-    // Круг (агрегат над собственным потомком, цикл агрегатов) так не упорядочить — отказ до записи с самим кругом (хвост
-    // ревью доработок после 1.2.0: раньше обход молча ставил потомка раньше предка)
+    // предок раньше потомка: потомка класса, которого ещё нет, база отклоняет. Круг родителей (модель, собранная мимо
+    // hub()) так не упорядочить — отказ до записи с самим кругом (хвост ревью доработок после 1.2.0: раньше обход молча
+    // ставил потомка раньше предка)
     const ordered = [];
     const path = [];
     const visit = (m) => {
@@ -21,23 +29,21 @@ export async function syncModels(db, models, opts = {}) {
             return;
         const at = path.indexOf(m);
         if (at >= 0) {
-            throw new LetopisError('invalid_class', `syncModels: модели зависят друг от друга по кругу: ${[...path.slice(at), m].map((x) => x.name).join(' → ')} — `
-                + 'родителя и источник агрегата база ждёт раньше класса');
+            throw lerr('model.models_cycle', { cycle: [...path.slice(at), m].map((x) => x.name).join(' → ') });
         }
         path.push(m);
         if (m.parent && models.includes(m.parent))
             visit(m.parent);
-        for (const a of Object.values(m.describe().aggregate ?? {})) {
-            const src = models.find((x) => x.name === a.of);
-            if (src)
-                visit(src);
-        }
         path.pop();
         ordered.push(m);
     };
     models.forEach(visit);
+    // у корня connect({ admin }) классы пишет администраторский пул с той же сессией (план 2.0, 7.9 №3): правка класса
+    // со строками требует прав, которых у роли приложения может не быть
+    const adminTx = internalsOf(db)?.adminTx;
+    const run = (fn) => (adminTx ? adminTx(fn) : db.transaction(fn));
     try {
-        await db.transaction(async (tx) => {
+        await run(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
@@ -77,8 +83,12 @@ export function schemaToTs(s, indent = '') {
         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 branches = (s.anyOf ?? s.oneOf);
+    // ветки из одних required у объекта с полями — условие, а не форма: тип — сам объект (план 2.0, 7.5 №1)
+    const onlyRequired = Array.isArray(branches) && s.properties !== undefined
+        && branches.every((b) => Object.keys(b).every((k) => k === 'required'));
+    if (Array.isArray(branches) && !onlyRequired)
+        return branches.map((b) => schemaToTs(b, indent)).join(' | ');
     const types = Array.isArray(s.type) ? s.type : [s.type];
     return types.map((t) => {
         switch (t) {
@@ -104,20 +114,40 @@ export function schemaToTs(s, indent = '') {
         }
     }).join(' | ');
 }
-/** Объявления `<Класс>Data` и `<Класс>Links` для классов реестра (кроме системных). */
+/**
+ * Объявления `<Класс>Data` и `<Класс>Links` для классов реестра и `<Класс>Model` — имя, алиас, концы с классами целей
+ * и предки (ModelLike, typed.ts), — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`
+ * (план 2.0, этап 4, п. 1). Классы арендатора System (системные и классы сидов пакета) — только с includeSystem
+ * (`letopis types --system`); без него системные классы даёт встроенный набор SystemModels. Пометка в первой строке —
+ * запись каталога model.types_header.
+ */
 export function generateTypes(registry, opts = {}) {
-    const out = ['// Сгенерировано letopis types — не править руками.', ''];
+    const out = [`// ${lmsg('model.types_header')}`, ''];
+    const models = [];
+    const lit = (v) => JSON.stringify(v);
     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`);
+        // идентификатор TypeScript — буквы Unicode, цифры, _ и $: кириллические имена классов допустимы (план 2.0, 7.5 №1)
+        if (!/^[\p{L}_$][\p{L}\p{N}_$]*$/u.test(c.name))
+            throw lerr('model.types_class_name', { name: c.name });
         // 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` : ''}}`, '');
+        // объектный литерал — интерфейс; класс без полей, union и открытая схема — псевдоним типа (иначе неверный TypeScript)
+        const data = schemaToTs(open);
+        out.push(/^\{[\s\S]*\}$/.test(data) && !/\}\s*&/.test(data) ? `export interface ${c.name}Data ${data}` : `export type ${c.name}Data = ${data};`);
+        const required = (e) => e.required === true || (e.min ?? 0) > 0;
+        const ends = Object.entries(c.ends).map(([role, e]) => `  ${lit(role)}${required(e) ? '' : '?'}: ${e.many ? 'string[]' : 'string'};`);
+        out.push(`export interface ${c.name}Links {${ends.length ? `\n${ends.join('\n')}\n` : ''}}`);
+        // концы с классами целей и предки — переходы, слоты и семейства строгих типов (typed.ts: ModelLike)
+        const specs = Object.entries(c.ends).map(([role, e]) => {
+            const targets = (Array.isArray(e.class) ? e.class : [e.class]).map(lit).join(' | ');
+            return `      ${lit(role)}: { targets: ${targets}; many: ${e.many === true}; required: ${required(e)} };`;
+        });
+        out.push(`export interface ${c.name}Model {`, `  readonly name: ${lit(c.name)};`, ...(c.alias ? [`  readonly alias: ${lit(c.alias)};`] : []), '  readonly __types?: {', `    data: ${c.name}Data;`, `    links: ${c.name}Links;`, `    ends: {${specs.length ? `\n${specs.join('\n')}\n    ` : ''}};`, `    ancestors: ${(c.ancestors.length ? c.ancestors : [c.name]).map(lit).join(' | ')};`, '  };', '}', '');
+        models.push(`${c.name}Model`);
     }
+    out.push(`export type Models = readonly [${models.join(', ')}];`, '');
     return out.join('\n');
 }

package/dist/tx.d.ts

@@ -31,6 +31,21 @@ export declare function isTransient(e: unknown): boolean;
 export declare function isLogConflict(e: unknown): boolean;
 /** Обрыв связи: сокет закрыт или серверный процесс завершён (FATAL) — исход отправленного неизвестен. */
 export declare function isConnectionError(e: unknown): boolean;
+/**
+ * Откатить транзакцию на зарезервированном соединении после ошибки: после обрыва в него не пишут (postgres.js 3.4
+ * уронил бы процесс необработанным TypeError), иначе — rollback, ошибка которого не важна (план 2.0, 7.4 №7).
+ */
+export declare function rollbackAfter(conn: {
+    unsafe(text: string): Promise<unknown>;
+}, err: unknown): Promise<void>;
+/**
+ * Вернуть зарезервированное соединение в пул. После обрыва сокета пул postgres.js уже перевёл
+ * соединение в закрытые (onclose); release() вернул бы его в открытые, и следующая операция
+ * писала бы в сокет null — необработанный TypeError роняет процесс.
+ */
+export declare function release(conn: {
+    release(): void;
+}, err: unknown): void;
 export declare const RETRIES = 3;
 export declare const retryDelay: (attempt: number) => Promise<void>;
 /** Нотификатор процесса: копит нагрузки сигналов и отправляет их пачкой раз в интервал. */
@@ -78,6 +93,16 @@ export interface TxContext {
     passes?: AclPasses;
     /** После успешной операции (продление сессии раз в минуту). */
     after?: () => void;
+    /**
+     * Сессия кончилась (no_session): выдать новую и вписать её токен в failed — у подключения по ключу APIKEY ключ
+     * обменивается заново. true — операцию можно повторить (один раз). Нет — no_session как есть.
+     */
+    renew?: (failed: TxContext) => Promise<boolean>;
+    /**
+     * Перед операцией (runTx, ExplicitTx.open): после простоя подключение проверяет, жива ли сессия, — иначе чтение под
+     * истёкшей сессией шло бы как анонимное и молча отдавало пустой ответ. Обновляет токен ctx, если сессию выдали заново.
+     */
+    before?: (ctx: TxContext) => Promise<void>;
     /**
      * После фиксации записи: нагрузки из letopis.changed (сигналы записи, session:<тег>) — кэш
      * результатов сбрасывает свои ответы сразу (§2.12); raw — запись через db.sql.
@@ -121,7 +146,7 @@ export declare class ExplicitTx implements Executor {
     /** В транзакции был сырой SQL (db.sql): после фиксации — весь кэш. */
     private raw;
     private constructor();
-    static open(ctx: TxContext): Promise<ExplicitTx>;
+    static open(ctx: TxContext, renewed?: boolean): Promise<ExplicitTx>;
     /** Транзакция ещё открыта (не зафиксирована и не откачена). */
     get active(): boolean;
     run<T>(fn: (tx: Tx) => Promise<T>, opts?: {

package/dist/tx.js

@@ -1,4 +1,4 @@
-import { LetopisError, fromDbError } from './errors.js';
+import { LetopisError, fromDbError, lerr, lmsg } from './errors.js';
 /** Транзиентные ошибки PG, которые снимает повтор: взаимная блокировка, сериализация. */
 export function isTransient(e) {
     const code = e.code;
@@ -17,23 +17,34 @@ export function isConnectionError(e) {
     const code = String(err?.code ?? '');
     return code.startsWith('CONNECTION_') || ['ECONNRESET', 'EPIPE', 'ECONNREFUSED', 'ETIMEDOUT', 'ECONNABORTED'].includes(code);
 }
+/**
+ * Откатить транзакцию на зарезервированном соединении после ошибки: после обрыва в него не пишут (postgres.js 3.4
+ * уронил бы процесс необработанным TypeError), иначе — rollback, ошибка которого не важна (план 2.0, 7.4 №7).
+ */
+export async function rollbackAfter(conn, err) {
+    if (isConnectionError(err))
+        return;
+    await conn.unsafe('rollback').catch(() => { });
+}
 /**
  * Вернуть зарезервированное соединение в пул. После обрыва сокета пул postgres.js уже перевёл
  * соединение в закрытые (onclose); release() вернул бы его в открытые, и следующая операция
  * писала бы в сокет null — необработанный TypeError роняет процесс.
  */
-function release(conn, err) {
+export function release(conn, err) {
     const e = err;
     if (e && !e.severity && isConnectionError(e))
         return;
     conn.release();
 }
-const commitUnknown = (cause) => Object.assign(new LetopisError('commit_unknown', 'связь оборвалась во время commit: транзакция могла зафиксироваться — '
-    + 'проверьте исход повтором той же операции с тем же ключом'), { cause });
-/** Взаимная блокировка в явной транзакции: повторить нужно весь блок (подсказка, как hintTxRetry 0.21). */
+const commitUnknown = (cause) => lerr('write.commit_unknown', undefined, { cause });
+/**
+ * Взаимная блокировка в явной транзакции: повторить нужно весь блок (подсказка, как hintTxRetry 0.21). Хвост —
+ * запись write.tx_retry_hint; он называет db.begin(), поэтому второй раз не дописывается.
+ */
 function hintTxRetry(e) {
     if (isTransient(e) && e instanceof Error && !e.message.includes('db.begin()')) {
-        e.message += ' — откатите транзакцию и повторите весь блок db.begin()';
+        e.message += lmsg('write.tx_retry_hint');
     }
     return e;
 }
@@ -147,6 +158,9 @@ const passSql = (q, ctx) => q.unsafe(`select set_config('letopis.acl', coalesce(
  */
 export async function runTx(ctx, fn, opts = {}) {
     const retries = opts.retries ?? RETRIES;
+    let renewed = false;
+    if (ctx.before)
+        await ctx.before(ctx);
     for (let attempt = 1;; attempt++) {
         let bodyDone = false;
         let dead = false;
@@ -193,13 +207,23 @@ export async function runTx(ctx, fn, opts = {}) {
                 await retryDelay(attempt);
                 continue;
             }
-            throw fromDbError(e);
+            const le = fromDbError(e);
+            // сессия кончилась по простою: подключение по ключу выдаёт новую — повтор один раз, транзакция уже откачена
+            if (!renewed && !bodyDone && ctx.renew && isNoSession(le)) {
+                renewed = true;
+                if (await ctx.renew(ctx)) {
+                    attempt--;
+                    continue;
+                }
+            }
+            throw le;
         }
         finally {
             release(conn, failure);
         }
     }
 }
+const isNoSession = (e) => e instanceof LetopisError && e.code === 'no_session';
 /** Исполнитель пула: каждая операция — своя транзакция с повторами. */
 export function poolExecutor(ctx) {
     return { explicit: false, run: (fn, opts) => runTx(ctx, fn, opts) };
@@ -223,7 +247,9 @@ export class ExplicitTx {
         this.ctx = ctx;
         this.conn = conn;
     }
-    static async open(ctx) {
+    static async open(ctx, renewed = false) {
+        if (!renewed && ctx.before)
+            await ctx.before(ctx);
         const conn = await ctx.sql.reserve();
         try {
             await conn.unsafe('begin isolation level read committed');
@@ -233,9 +259,13 @@ export class ExplicitTx {
                 ctx.passes.set(ctx, (await passSql(conn, ctx))[0]?.p);
         }
         catch (e) {
-            await conn.unsafe('rollback').catch(() => { });
-            conn.release();
-            throw fromDbError(e);
+            await rollbackAfter(conn, e);
+            release(conn, e);
+            const le = fromDbError(e);
+            // сессия кончилась по простою (как у runTx): подключение по ключу выдаёт новую — открыть ещё раз
+            if (!renewed && ctx.renew && isNoSession(le) && (await ctx.renew(ctx)))
+                return ExplicitTx.open(ctx, true);
+            throw le;
         }
         return new ExplicitTx(ctx, conn);
     }
@@ -245,7 +275,7 @@ export class ExplicitTx {
     }
     async run(fn, opts) {
         if (this.done)
-            throw new LetopisError('tx_required', 'транзакция db.begin() уже завершена');
+            throw lerr('write.tx_done');
         if (this.broken)
             throw this.broken;
         if (opts?.raw)
@@ -262,7 +292,7 @@ export class ExplicitTx {
     /** Advisory-блокировка до конца транзакции (отдельное от блокировок семейств пространство ключей). */
     async lock(...keys) {
         if (this.done)
-            throw new LetopisError('tx_required', 'lock(): транзакция db.begin() уже завершена');
+            throw lerr('write.lock_tx_done');
         await this.run((q) => q.unsafe('select pg_advisory_xact_lock(hashtextextended($1, 0))', [keys.join('|')]));
     }
     async commit() {
@@ -294,7 +324,7 @@ export class ExplicitTx {
             }));
             changed = rows[0]?.changed ?? null;
             if (res.command === 'ROLLBACK') {
-                this.failure = new LetopisError('tx_rolled_back', 'commit: PostgreSQL откатил транзакцию (в ней была ошибка)');
+                this.failure = lerr('write.tx_rolled_back');
                 throw this.failure;
             }
         }