letopis 0.21.0 → 1.0.0

package/dist/tx.js

@@ -1,82 +1,309 @@
+import { LetopisError, fromDbError } from './errors.js';
+/** Транзиентные ошибки PG, которые снимает повтор: взаимная блокировка, сериализация. */
+export function isTransient(e) {
+    const code = e.code;
+    return code === '40P01' || code === '40001';
+}
+/** Конфликт пары «id, номер версии» в журнале — параллельные удаление и создание одного id (§2.5). */
+export function isLogConflict(e) {
+    const err = e;
+    return err.code === '23505' && err.constraint_name === 'log_id_rev';
+}
+/** Обрыв связи: сокет закрыт или серверный процесс завершён (FATAL) — исход отправленного неизвестен. */
+export function isConnectionError(e) {
+    const err = e;
+    if (err?.severity)
+        return err.severity === 'FATAL' || err.severity === 'PANIC';
+    const code = String(err?.code ?? '');
+    return code.startsWith('CONNECTION_') || ['ECONNRESET', 'EPIPE', 'ECONNREFUSED', 'ETIMEDOUT', 'ECONNABORTED'].includes(code);
+}
 /**
- * Транзакции: db.begin() → tr (тот же API на выделенном соединении),
- * db.commit(tr) / db.rollback(tr) / tr.commit() / tr.rollback().
- * tr.lock(...) — pg_advisory_xact_lock (сериализация гонок, напр. двойная бронь).
+ * Вернуть зарезервированное соединение в пул. После обрыва сокета пул postgres.js уже перевёл
+ * соединение в закрытые (onclose); release() вернул бы его в открытые, и следующая операция
+ * писала бы в сокет null — необработанный TypeError роняет процесс.
  */
-// FILE: lib/src/tx.ts
-// VERSION: 1.0.0
-// START_MODULE_CONTRACT
-//   PURPOSE: Ручные транзакции и advisory-локи поверх зарезервированного pg-соединения.
-//   SCOPE: beginTx, lock
-//   DEPENDS: M-SQL
-//   LINKS: M-TX, V-M-TX
-//   ROLE: RUNTIME
-//   MAP_MODE: EXPORTS
-// END_MODULE_CONTRACT
-//
-// START_MODULE_MAP
-//   TxCtx - Ctx транзакции с методами commit()/rollback()
-//   beginTx - резервирует соединение, шлёт BEGIN, возвращает TxCtx
-//   lock - pg_advisory_xact_lock на составной ключ (только внутри транзакции)
-// END_MODULE_MAP
-//
-// START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
-// END_CHANGE_SUMMARY
-import { hintTxRetry, isTransient } from './sql.js';
-// START_CONTRACT: beginTx
-//   PURPOSE: Начать ручную транзакцию на зарезервированном соединении и вернуть TxCtx.
-//   INPUTS: { ctx: Ctx - базовый контекст с пулом sql }
-//   OUTPUTS: { Promise<TxCtx> - контекст с sql на резерве + commit()/rollback() }
-//   SIDE_EFFECTS: reserve() соединения из пула и BEGIN; commit/rollback шлют COMMIT/ROLLBACK и release() (идемпотентно через флаг done)
-//   LINKS: M-TX, V-M-TX, M-SQL
-// END_CONTRACT: beginTx
-export async function beginTx(ctx) {
-    const reserved = await ctx.sql.reserve();
-    const r = reserved;
-    await r.unsafe('BEGIN');
-    let done = false;
-    const finish = async (cmd) => {
-        if (done)
+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). */
+function hintTxRetry(e) {
+    if (isTransient(e) && e instanceof Error && !e.message.includes('db.begin()')) {
+        e.message += ' — откатите транзакцию и повторите весь блок db.begin()';
+    }
+    return e;
+}
+export const RETRIES = 3;
+export const retryDelay = (attempt) => new Promise((r) => setTimeout(r, 40 * attempt + Math.random() * 40));
+/** Нотификатор процесса: копит имена классов и отправляет их пачкой раз в интервал. */
+export class Notifier {
+    sql;
+    channel;
+    intervalMs;
+    onError;
+    queue = new Set();
+    timer = null;
+    stopped = false;
+    flushing = Promise.resolve();
+    constructor(sql, channel, intervalMs, onError = () => { }) {
+        this.sql = sql;
+        this.channel = channel;
+        this.intervalMs = intervalMs;
+        this.onError = onError;
+    }
+    /** Добавить классы из letopis.changed (строка через запятую). */
+    add(changed) {
+        if (!changed || this.stopped)
+            return;
+        for (const c of changed.split(','))
+            if (c)
+                this.queue.add(c);
+        if (!this.timer && this.queue.size)
+            this.timer = setTimeout(() => void this.flush(), this.intervalMs);
+    }
+    /** Отправить накопленное сейчас (вызывается по таймеру и при закрытии). */
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (!this.queue.size)
+            return this.flushing;
+        const classes = [...this.queue];
+        this.queue.clear();
+        this.flushing = this.flushing.then(() => this.sql `select pg_notify(${this.channel}, c) from unnest(${classes}::text[]) as c`.then(() => undefined, this.onError));
+        return this.flushing;
+    }
+    async close() {
+        this.stopped = true;
+        await this.flush();
+    }
+}
+/** Кэш подписанных пропусков прав одного подключения: по токену, актору и арендатору. */
+export class AclPasses {
+    schema;
+    ttlMs;
+    max;
+    map = new Map();
+    /** schema — имя схемы в кавычках (для вызова acl_token). */
+    constructor(schema, ttlMs = 60_000, max = 10_000) {
+        this.schema = schema;
+        this.ttlMs = ttlMs;
+        this.max = max;
+    }
+    key(c) {
+        return `${c.token ?? ''}\u0001${c.account ?? ''}\u0001${c.tenant ?? ''}`;
+    }
+    get(c) {
+        const v = this.map.get(this.key(c));
+        if (!v)
+            return null;
+        if (Date.now() - v.at > this.ttlMs) {
+            this.map.delete(this.key(c));
+            return null;
+        }
+        return v.pass;
+    }
+    set(c, pass) {
+        if (!pass)
             return;
-        done = true;
+        if (this.map.size >= this.max)
+            this.map.delete(this.map.keys().next().value);
+        this.map.set(this.key(c), { pass, at: Date.now() });
+    }
+    /** Права изменились (сигнал строк прав, auth.switch): все пропуска — заново. */
+    clear() {
+        this.map.clear();
+    }
+}
+const changedList = (changed) => (changed ? changed.split(',').filter(Boolean) : []);
+/** Служебные настройки транзакции одним оператором (уходит конвейером с первым запросом). */
+const setupSql = (q, ctx, pass) => q `select set_config('letopis.token', ${ctx.token ?? ''}, true),
+           set_config('letopis.account', ${ctx.account ?? ''}, true),
+           set_config('letopis.tenant', ${ctx.tenant ?? ''}, true),
+           set_config('letopis.acl', ${pass ?? ''}, true),
+           set_config('letopis.notify', 'deferred', true),
+           set_config('letopis.reason', ${ctx.reason ?? ''}, true),
+           set_config('TimeZone', 'UTC', true)`;
+/** Пропуска нет — взять его в этой же транзакции (им пользуются и её запросы). */
+const passSql = (q, ctx) => q.unsafe(`select set_config('letopis.acl', coalesce(${ctx.passes.schema}.acl_token(), ''), true) as p`);
+/**
+ * Операция одной транзакцией с контекстом сессии и повтором при транзиентных ошибках и конфликте
+ * журнала. Ошибки базы переводятся в LetopisError. read — операция только читает: сигналы не собираются.
+ */
+export async function runTx(ctx, fn, opts = {}) {
+    const retries = opts.retries ?? RETRIES;
+    for (let attempt = 1;; attempt++) {
+        let bodyDone = false;
+        let dead = false;
+        let failure = null;
+        // своё зарезервированное соединение, а не sql.begin: после гибели серверного процесса
+        // postgres.js 3.4 шлёт rollback в закрытый сокет и роняет процесс необработанным TypeError
+        const conn = await ctx.sql.reserve();
         try {
-            await r.unsafe(cmd);
+            let changed = null;
+            // begin, служебный оператор и первый запрос операции уходят конвейером (§2.9); время — в UTC;
+            // execute(): запросы postgres.js ленивые — без него первый запрос fn ушёл бы раньше настроек
+            const begin = conn.unsafe('begin isolation level read committed').execute();
+            const pass = ctx.passes?.get(ctx) ?? null;
+            const setup = setupSql(conn, ctx, pass).execute();
+            const fetch = !pass && ctx.passes && ctx.token ? passSql(conn, ctx).execute() : null;
+            const [, , got, out] = await Promise.all([begin, setup, fetch, fn(conn)]);
+            if (got)
+                ctx.passes.set(ctx, got[0]?.p);
+            bodyDone = true;
+            // чтение letopis.changed и COMMIT — одним конвейером: порядок на соединении сохраняется (чтение
+            // идёт до фиксации), а круг до базы на запись — один (бенч этапа 7: −0,8 мс на запись)
+            if (opts.read) {
+                await conn.unsafe('commit');
+            }
+            else {
+                const [rows] = await Promise.all([conn `select current_setting('letopis.changed', true) as changed`, conn.unsafe('commit')]);
+                changed = rows[0]?.changed ?? null;
+            }
+            ctx.notifier?.add(changed);
+            if (changed)
+                ctx.onChanged?.(changedList(changed), opts.raw === true);
+            ctx.after?.();
+            return out;
+        }
+        catch (e) {
+            failure = e;
+            dead = isConnectionError(e);
+            if (!dead)
+                await conn.unsafe('rollback').catch(() => { });
+            // обрыв во время COMMIT: транзакция могла зафиксироваться — не повторяем (§2.5)
+            if (bodyDone && !opts.read && dead)
+                throw commitUnknown(e);
+            if (attempt <= retries && (isTransient(e) || isLogConflict(e))) {
+                await retryDelay(attempt);
+                continue;
+            }
+            throw fromDbError(e);
         }
         finally {
-            r.release();
+            release(conn, failure);
         }
-    };
-    return {
-        ...ctx,
-        sql: reserved,
-        inTx: true,
-        userTx: true,
-        commit: () => finish('COMMIT'),
-        rollback: () => finish('ROLLBACK'),
-    };
+    }
+}
+/** Исполнитель пула: каждая операция — своя транзакция с повторами. */
+export function poolExecutor(ctx) {
+    return { explicit: false, run: (fn, opts) => runTx(ctx, fn, opts) };
 }
-/** Advisory-lock на составной ключ; живёт до конца транзакции. */
-// START_CONTRACT: lock
-//   PURPOSE: Взять pg_advisory_xact_lock на составной ключ (сериализация гонок; живёт до конца транзакции).
-//   INPUTS: { ctx: Ctx - контекст (должен быть inTx); keys: (string|number)[] - части составного ключа }
-//   OUTPUTS: { Promise<void> }
-//   SIDE_EFFECTS: SELECT pg_advisory_xact_lock(hashtextextended(...)); вне транзакции бросает 'letopis: lock() works only inside db.begin() transaction'; на transient-ошибке (напр. deadlock 40P01) вызывает hintTxRetry и пробрасывает
-//   LINKS: M-TX, V-M-TX, M-SQL
-// END_CONTRACT: lock
-export async function lock(ctx, ...keys) {
-    if (!ctx.inTx) {
-        throw new Error('letopis: lock() works only inside db.begin() transaction (pg_advisory_xact_lock)');
-    }
-    // START_BLOCK_ADVISORY_LOCK
-    try {
-        await ctx.sql.unsafe('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [keys.join('|')]);
-    }
-    catch (e) {
-        // встречный порядок lock() двух транзакций → deadlock 40P01 (PG убивает одну)
-        if (isTransient(e))
-            hintTxRetry(e);
-        throw e;
-    }
-    // END_BLOCK_ADVISORY_LOCK
+/**
+ * Явная транзакция db.begin() (этап 4, п. 9): одно зарезервированное соединение, read committed.
+ * Ошибка любого запроса ломает транзакцию (правило §2.5): дальше каждый вызов бросает исходную
+ * ошибку, rollback() проходит, commit() откатывает и бросает её же. Ответ ROLLBACK на COMMIT
+ * (PostgreSQL так фиксирует сломанную транзакцию) — тоже ошибка.
+ */
+export class ExplicitTx {
+    ctx;
+    conn;
+    explicit = true;
+    broken = null;
+    done = false;
+    failure = null;
+    /** В транзакции был сырой SQL (db.sql): после фиксации — весь кэш. */
+    raw = false;
+    constructor(ctx, conn) {
+        this.ctx = ctx;
+        this.conn = conn;
+    }
+    static async open(ctx) {
+        const conn = await ctx.sql.reserve();
+        try {
+            await conn.unsafe('begin isolation level read committed');
+            const pass = ctx.passes?.get(ctx) ?? null;
+            await setupSql(conn, ctx, pass);
+            if (!pass && ctx.passes && ctx.token)
+                ctx.passes.set(ctx, (await passSql(conn, ctx))[0]?.p);
+        }
+        catch (e) {
+            await conn.unsafe('rollback').catch(() => { });
+            conn.release();
+            throw fromDbError(e);
+        }
+        return new ExplicitTx(ctx, conn);
+    }
+    /** Транзакция ещё открыта (не зафиксирована и не откачена). */
+    get active() {
+        return !this.done;
+    }
+    async run(fn, opts) {
+        if (this.done)
+            throw new LetopisError('tx_required', 'транзакция db.begin() уже завершена');
+        if (this.broken)
+            throw this.broken;
+        if (opts?.raw)
+            this.raw = true;
+        try {
+            return await fn(this.conn);
+        }
+        catch (e) {
+            const err = fromDbError(hintTxRetry(e));
+            this.broken = err;
+            throw err;
+        }
+    }
+    /** Advisory-блокировка до конца транзакции (отдельное от блокировок семейств пространство ключей). */
+    async lock(...keys) {
+        if (this.done)
+            throw new LetopisError('tx_required', 'lock(): транзакция db.begin() уже завершена');
+        await this.run((q) => q.unsafe('select pg_advisory_xact_lock(hashtextextended($1, 0))', [keys.join('|')]));
+    }
+    async commit() {
+        if (this.done) {
+            if (this.failure)
+                throw this.failure;
+            return;
+        }
+        this.done = true;
+        if (this.broken) {
+            if (!isConnectionError(this.broken))
+                await this.conn.unsafe('rollback').catch(() => { });
+            release(this.conn, this.broken);
+            this.failure = this.broken;
+            throw this.broken;
+        }
+        let changed = null;
+        try {
+            // чтение letopis.changed и COMMIT — одним конвейером (как в runTx); обрыв — исход неизвестен
+            const [rows, res] = await Promise.all([this.conn.unsafe(`select current_setting('letopis.changed', true) as changed`), this.conn.unsafe('commit')]);
+            changed = rows[0]?.changed ?? null;
+            if (res.command === 'ROLLBACK') {
+                this.failure = new LetopisError('tx_rolled_back', 'commit: PostgreSQL откатил транзакцию (в ней была ошибка)');
+                throw this.failure;
+            }
+        }
+        catch (e) {
+            this.failure ??= isConnectionError(e) ? commitUnknown(e) : fromDbError(e);
+            release(this.conn, e);
+            throw this.failure;
+        }
+        this.conn.release();
+        this.ctx.notifier?.add(changed);
+        if (changed)
+            this.ctx.onChanged?.(changedList(changed), this.raw);
+        this.ctx.after?.();
+    }
+    async rollback() {
+        if (this.done)
+            return;
+        this.done = true;
+        try {
+            // соединение, оборванное ошибкой, не трогаем: postgres.js уронил бы процесс записью в закрытый сокет
+            if (!isConnectionError(this.broken))
+                await this.conn.unsafe('rollback');
+        }
+        catch (e) {
+            // соединение могло оборваться — транзакция откатится сама
+            release(this.conn, e);
+            return;
+        }
+        release(this.conn, this.broken);
+    }
 }

package/dist/typed.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Типы цепочек по моделям (план, этап 3, п. 9): `connect({ models })` даёт типы шагов по именам и
+ * алиасам классов, типы строк ответа и фильтров. Допустимость переходов проверяется во время
+ * выполнения, как в 0.21. Модель описана структурно (ModelLike), чтобы основная точка входа не
+ * зависела от Zod: модели letopis/model ей соответствуют.
+ */
+import type { ChainCore, StepFn } from './chain.js';
+import type { Cursor, Op, Path, Row, Scalar } from './types.js';
+import type { IncMarker } from './write.js';
+/** То, что цепочкам нужно от модели: имя, алиас и выведенные типы данных и концов. */
+export interface ModelLike<N extends string = string, D = unknown, L = unknown, A extends string = string> {
+    readonly name: N;
+    readonly alias?: A;
+    readonly __types?: {
+        data: D;
+        links: L;
+    };
+}
+export type AnyModelLike = ModelLike<string, any, any, any>;
+type DataOf<C> = C extends ModelLike<string, infer D, unknown, string> ? (D extends Record<string, unknown> ? D : Record<string, unknown>) : Record<string, unknown>;
+type LinksOf<C> = C extends ModelLike<string, unknown, infer L, string> ? (L extends Record<string, unknown> ? L : Record<string, string>) : Record<string, string>;
+/** Строка ответа класса C. */
+export type RowOf<C> = Row<DataOf<C>, LinksOf<C>>;
+/** Фильтр по значению поля: равенство, оператор, вложенный объект любой глубины. */
+export type FieldFilterOf<T> = Op | (T extends readonly unknown[] ? T : T extends Record<string, unknown> ? {
+    [P in keyof T]?: FieldFilterOf<T[P]>;
+} : T extends Scalar ? T | null : never);
+/** Фильтр шага класса C: id, список id, строка ответа, or(…) или объект полей и ролей. */
+export type FilterOf<C> = string | string[] | Op | {
+    id: string;
+    class: string;
+} | ({
+    [P in keyof DataOf<C>]?: FieldFilterOf<DataOf<C>[P]>;
+} & {
+    [R in keyof LinksOf<C>]?: string | {
+        id: string;
+    } | null;
+} & {
+    id?: string | string[];
+});
+/** Шаги по именам и алиасам моделей M. */
+export type StepsOf<M extends readonly AnyModelLike[]> = {
+    [K in M[number] as K['name']]: (filter?: FilterOf<K>) => TypedChain<K, M>;
+} & {
+    [K in M[number] as K extends ModelLike<string, unknown, unknown, infer A> ? (string extends A ? never : A) : never]: (filter?: FilterOf<K>) => TypedChain<K, M>;
+};
+/** Патч update: поля любой глубины необязательны; inc() — только у числовых полей (§2.5). */
+export type PatchOf<T> = {
+    [P in keyof T]?: T[P] extends number | undefined ? T[P] | IncMarker : T[P] extends readonly unknown[] | undefined ? T[P] : T[P] extends Record<string, unknown> | undefined ? PatchOf<NonNullable<T[P]>> : T[P];
+};
+type Retyped = 'paths' | 'rows' | 'first' | 'versions' | 'limit' | 'offset' | 'sort' | 'asOf' | 'after' | 'withDeleted' | 'deep' | 'exact' | 'alias' | 'tags' | 'owner' | 'create' | 'update' | 'upsert' | 'delete' | 'anonymize' | 'reclass' | 'forUpdate' | 'restore' | 'purge' | 'rekey' | 'cache';
+/** Цепочка с текущим классом C: терминалы отдают RowOf<C>, шаги — по моделям M; роли и прочие классы — без типов. */
+export type TypedChain<C, M extends readonly AnyModelLike[]> = Omit<ChainCore, Retyped> & {
+    paths(): Promise<Path[]>;
+    rows(): Promise<RowOf<C>[]>;
+    first(): Promise<RowOf<C> | null>;
+    versions(opts?: {
+        follow?: boolean;
+    }): Promise<RowOf<C>[]>;
+    limit(n: number): TypedChain<C, M>;
+    offset(n: number): TypedChain<C, M>;
+    sort(field: 'at' | 'rev' | 'id' | `data.${string}`, dir?: 'asc' | 'desc' | boolean): TypedChain<C, M>;
+    asOf(t: string | Date): TypedChain<C, M>;
+    after(cursor: Cursor): TypedChain<C, M>;
+    withDeleted(): TypedChain<C, M>;
+    deep(max?: number): TypedChain<C, M>;
+    exact(): TypedChain<C, M>;
+    alias(name: string): TypedChain<C, M>;
+    tags(v: string | string[] | Op): TypedChain<C, M>;
+    owner(v: string | {
+        id: string;
+    }): TypedChain<C, M>;
+    create(data: Partial<DataOf<C>>): TypedChain<C, M>;
+    update(patch?: PatchOf<DataOf<C>>, opts?: {
+        rev?: number;
+    }): TypedChain<C, M>;
+    upsert(data: Partial<DataOf<C>>): TypedChain<C, M>;
+    delete(opts?: {
+        confirm?: boolean;
+    }): TypedChain<C, M>;
+    anonymize(fields: (keyof DataOf<C> & string)[]): TypedChain<C, M>;
+    reclass(cls: string, data?: Record<string, unknown>): TypedChain<unknown, M>;
+    forUpdate(): TypedChain<C, M>;
+    restore(): TypedChain<C, M>;
+    purge(opts?: {
+        confirm?: boolean;
+    }): TypedChain<C, M>;
+    rekey(patch: Partial<DataOf<C>> & Partial<Record<keyof LinksOf<C>, string | {
+        id: string;
+    }>>): TypedChain<C, M>;
+    cache(opts?: {
+        ttl?: number;
+    }): TypedChain<C, M>;
+} & StepsOf<M> & {
+    [step: string]: StepFn;
+};
+export {};

package/dist/typed.js

@@ -0,0 +1 @@
+export {};