letopis 0.20.3 → 1.0.0

package/dist/watch.js

@@ -0,0 +1,168 @@
+/**
+ * Подписка на изменения (план, этап 6, п. 5): `for await (const ev of db.watch({ from }))`.
+ *
+ * «now» — голова в момент подписки: курсор с горизонта и снимок, чтобы не отдать транзакции,
+ * зафиксированные до подписки, но ещё не ушедшие за горизонт.
+ *
+ * Курсор — (tx, seq) записи журнала: события читаются только ниже горизонта завершённых
+ * транзакций (pg_snapshot_xmin) — транзакцию с меньшим номером, зафиксированную позже, курсор уже
+ * не обгонит, поэтому событий нет ни потерянных, ни повторных. Поток стоит, пока открыта более
+ * старая пишущая транзакция (горизонт общий для кластера); метрика — lag(). Чтение идёт под RLS
+ * журнала: каждый видит только своё. Сигнал базы с именем класса только будит подписку (чужие
+ * классы — не будят); без LISTEN и на случай потери сигнала — запасной опрос.
+ *
+ * Курсор подписчика старше яруса all политики хранения его классов — cursor_expired: события могли
+ * проредиться, нужно перечитать текущее состояние и подписаться заново.
+ */
+import { LetopisError } from './errors.js';
+import { toRow } from './sql.js';
+/** Курсор события: «tx:seq[:время][~снимок]». */
+const encode = (p) => `${p.tx}:${p.seq}${p.at ? `:${p.at}` : ''}${p.snap ? `~${p.snap}` : ''}`;
+function decode(c) {
+    const [head, snap] = c.split('~');
+    const m = /^(\d+):(\d+)(?::(.+))?$/.exec(head);
+    if (!m || (snap !== undefined && !/^\d+:\d+:[\d,]*$/.test(snap))) {
+        throw new LetopisError('invalid_query', `watch: курсор ${c} — ожидается курсор события`);
+    }
+    return { tx: m[1], seq: m[2], at: m[3] ?? null, ...(snap ? { snap } : {}) };
+}
+/** Снимок ещё нужен: курсор не дошёл до его xmax. */
+const keepSnap = (snap, tx) => snap && BigInt(tx) < BigInt(snap.split(':')[1]) ? snap : undefined;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class Subscription {
+    ctx;
+    opts;
+    pos = null;
+    buf = [];
+    closed = false;
+    wake = null;
+    dirty = true;
+    off = null;
+    timer = null;
+    failure = null;
+    batch;
+    pollMs;
+    /** 'now' — голова журнала в момент подписки (запрос уходит сразу). */
+    start = null;
+    constructor(ctx, opts) {
+        this.ctx = ctx;
+        this.opts = opts;
+        this.batch = opts.batch ?? 500;
+        this.pollMs = opts.pollMs ?? 1000;
+        const from = opts.from ?? 'now';
+        if (from === 'start')
+            this.pos = { tx: '0', seq: '0', at: null };
+        else if (from !== 'now')
+            this.pos = decode(from);
+        else {
+            this.start = this.head();
+            this.start.catch(() => { });
+        }
+        if (ctx.onSignal) {
+            const watched = ctx.classes ? new Set(ctx.classes) : null;
+            this.off = ctx.onSignal((name) => {
+                if (name === '' || name.startsWith('session:'))
+                    return;
+                if (watched && name !== '*' && !watched.has(name))
+                    return;
+                this.dirty = true;
+                this.wake?.();
+            });
+        }
+        this.timer = setInterval(() => {
+            this.dirty = true;
+            this.wake?.();
+        }, this.pollMs);
+        this.timer.unref?.();
+    }
+    /** Курсор последнего выданного события (или начальной точки). */
+    get cursor() {
+        return this.pos ? encode(this.pos) : null;
+    }
+    async head() {
+        const [r] = await this.ctx.exec.run((q) => q.unsafe(`select tx::text as tx, seq::text as seq, snap::text as snap from ${this.ctx.S}.watch_head()`), { read: true });
+        return { tx: r.tx, seq: r.seq, at: null, snap: r.snap };
+    }
+    /** Следующая пачка событий ниже горизонта; пусто — горизонт ещё не дошёл или событий нет. */
+    async fetch() {
+        if (!this.pos)
+            this.pos = await (this.start ?? this.head());
+        const p = this.pos;
+        const rows = await this.ctx.exec.run((q) => q.unsafe(`select l.tx::text as tx, l.seq::text as seq, jsonb_build_object('id', l.id, 'rev', l.rev, 'class', l.class, 'tenant', l.tenant, `
+            + `'owner', l.owner, 'links', l.links, 'data', l.data, 'tags', l.tags, 'at', l.at, 'author', l.author, 'agent', l.agent, `
+            + `'op', l.op, 'reason', l.reason, 'moved', l.moved) as row `
+            + `from ${this.ctx.S}.watch_read($1::text::xid8, $2::bigint, $3::text::timestamptz, $4::text[], $5::int, $6::text::pg_snapshot) l`, [p.tx, p.seq, p.at, this.ctx.classes, this.batch, p.snap ?? null]), { read: true });
+        for (const r of rows) {
+            const row = toRow(r.row);
+            const snap = keepSnap(p.snap, r.tx);
+            this.pos = { tx: r.tx, seq: r.seq, at: row.at, ...(snap ? { snap } : {}) };
+            this.buf.push({ cursor: encode(this.pos), row, id: row.id, class: row.class, op: row.op, rev: row.rev, at: row.at });
+        }
+        return rows.length;
+    }
+    async next() {
+        let empty = 0;
+        for (;;) {
+            if (this.failure)
+                throw this.failure;
+            if (this.buf.length)
+                return { value: this.buf.shift(), done: false };
+            if (this.closed)
+                return { value: undefined, done: true };
+            if (this.dirty) {
+                try {
+                    const n = await this.fetch();
+                    if (n) {
+                        empty = 0;
+                        continue;
+                    }
+                }
+                catch (e) {
+                    this.failure = e;
+                    this.close();
+                    throw e;
+                }
+                // сигнал был, а событий ниже горизонта ещё нет: короткие повторы, затем — запасной опрос
+                if (++empty < 40) {
+                    await sleep(Math.min(25 * empty, 250));
+                    continue;
+                }
+                this.dirty = false;
+                empty = 0;
+            }
+            await new Promise((r) => {
+                this.wake = () => {
+                    this.wake = null;
+                    r();
+                };
+            });
+        }
+    }
+    /**
+     * Отставание, мс: сколько ждёт самое старое событие, которое уже зафиксировано, но ещё не ушло за
+     * горизонт (его держит более старая открытая транзакция); 0 — ждать нечего.
+     */
+    async lag() {
+        const p = this.pos ?? (await (this.start ?? this.head()));
+        const [r] = await this.ctx.exec.run((q) => q.unsafe(`select coalesce(extract(epoch from clock_timestamp() - min(l.at)) * 1000, 0)::float8 as ms from ${this.ctx.S}.log l `
+            + `where (l.tx, l.seq) > ($1::text::xid8, $2::bigint) and l.tx >= pg_snapshot_xmin(pg_current_snapshot())`
+            + `${this.ctx.classes ? ' and l.class = any ($3::text[])' : ''}`, (this.ctx.classes ? [p.tx, p.seq, this.ctx.classes] : [p.tx, p.seq])), { read: true });
+        return Number(r?.ms ?? 0);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.off?.();
+        if (this.timer)
+            clearInterval(this.timer);
+        this.wake?.();
+    }
+    async return() {
+        this.close();
+        return { value: undefined, done: true };
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}

package/dist/write.d.ts

@@ -1,82 +1,125 @@
-import type { Row, ChainMods } from './types.js';
-import { type Ctx, type Step } from './sql.js';
-export declare class ValidationError extends Error {
-    issues: {
-        field: string;
-        message?: string;
-    }[];
-    constructor(cls: string, issues: {
-        field: string;
-        message?: string;
-    }[]);
+import type { ClassInfo, Registry } from './registry.js';
+import { type AggSpec, type BuiltQuery, type ReadMode, type Step } from './sql.js';
+import type { Tx } from './tx.js';
+import type { ChainMods, Row } from './types.js';
+/** Метка приращения; Symbol.for — маркер узнаёт и вторая копия пакета в процессе. */
+export declare const INC: unique symbol;
+export interface IncMarker {
+    readonly [INC]: true;
+    readonly by: number;
+    readonly start?: number;
 }
-interface RawRow {
-    partition: string;
-    id: string;
-    class: string;
-    data: Record<string, unknown>;
-    links: Record<string, string> | null;
-    tags: string[] | null;
-    account: string;
-    owner: string;
-    updated: string | Date;
-    deleted: string | Date | null;
-}
-export declare function toRow(r: RawRow): Row;
-/** Прочитать актуальные строки по цепочке. */
-export declare function readRows(ctx: Ctx, steps: Step[], mods?: ChainMods): Promise<Row[]>;
-/**
- * Deep-merge патча в базу: меняются ТОЛЬКО указанные листья.
- * Вложенные plain-объекты сливаются рекурсивно; массивы/скаляры/null — заменяются.
- */
-export declare function deepMerge(base: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
-/**
- * .create(data) — «чтобы сущность существовала»:
- *  - id не задан → INSERT (id по IdGen класса; links = концы из пути + слоты);
- *  - id известен (Класс(id) / data.id / вычислен v5): есть → новая версия (deep-merge),
- *    нет → INSERT с этим id (идемпотентный create, REST-PUT семантика);
- *  - фильтр-объект / pivot — ошибка: create не ищет, это update().
- */
-export declare function createOp(ctx: Ctx, steps: Step[], mods: ChainMods, data: Record<string, unknown>): Promise<Row[]>;
-/**
- * .update(data?) — новая версия КАЖДОГО найденного путём (deep-merge листьев);
- * цели: Класс() ≡ Класс({}) — все в границах контекста, id/фильтр/pivot — как в чтении.
- * Не найдено → [] — update НИКОГДА не создаёт.
- */
-export declare function updateOp(ctx: Ctx, steps: Step[], mods: ChainMods, data: Record<string, unknown>): Promise<Row[]>;
 /**
- * .anonymize(fields): GDPR-затирание — новая версия с '[erased]' в указанных string-полях
- * + тег 'anonymized'. Только string-поля (по Schema); история сохраняется (см. README).
+ * Приращение в update: `update({ balance: inc(-300) })` — величина прибавляется в базе, внутри
+ * оператора, над свежей строкой (функция inc). Поля нет — ошибка; `{ start }` — начать с него.
  */
-export declare function anonymizeOp(ctx: Ctx, steps: Step[], mods: ChainMods, fields: string[]): Promise<Row[]>;
-/**
- * .delete({confirm}): цели = фильтр последнего шага + контекст-связи.
- * confirm: true — серверное удаление (триггер entity_delete: tombstone + рекурсивный
- * каскад + advisory-lock); возвращает ВСЁ удалённое (цели + каскад) с $deleted: true.
- * Без confirm — ПРЕВЬЮ: то же замыкание (цели + каскад), но БД не трогается.
- */
-export declare function delOp(ctx: Ctx, steps: Step[], mods: ChainMods, confirm: boolean): Promise<Row[]>;
+export declare function inc(by: number, opts?: {
+    start?: number;
+}): IncMarker;
+export declare const isInc: (v: unknown) => v is IncMarker;
+export type PlanOp = {
+    kind: 'create';
+    data: Record<string, unknown>;
+} | {
+    kind: 'update';
+    data: Record<string, unknown>;
+    rev?: number;
+} | {
+    kind: 'upsert';
+    data: Record<string, unknown>;
+} | {
+    kind: 'delete';
+    confirm: boolean;
+} | {
+    kind: 'anonymize';
+    fields: string[];
+} | {
+    kind: 'reclass';
+    cls: string;
+    data?: Record<string, unknown>;
+} | {
+    kind: 'restore';
+} | {
+    kind: 'purge';
+    confirm: boolean;
+} | {
+    kind: 'rekey';
+    data: Record<string, unknown>;
+};
+/** Значение слота: id, список id, строка ответа или ленивая цепочка (в той же транзакции). */
+export type SlotValue = string | string[] | {
+    id: string;
+} | null | {
+    plan: Step[];
+    mods: ChainMods;
+};
+export interface Slot {
+    /** Роль (конец) записываемого класса. */
+    role: string;
+    op: 'set' | 'unset' | 'add' | 'remove';
+    value: SlotValue;
+}
+/** Строка ответа записи (результат upsert — $upsert, превью удаления — $action — поля Row). */
+export type WriteRow = Row;
+export interface IncSpec {
+    path: string[];
+    by: number;
+    start?: number;
+}
+/** Патч update → остаток для merge и список приращений. Недопустимое — invalid_data до отправки. */
+export declare function splitPatch(patch: Record<string, unknown>): {
+    rest: Record<string, unknown>;
+    incs: IncSpec[];
+};
+/** Всё, что проверяется без базы, — до отправки первого оператора (§2.5). */
+export declare function precheckPlan(reg: Registry, steps: Step[]): void;
+export interface WriteCtx {
+    reg: Registry;
+    schema: string;
+    q: Tx;
+    /** Арендатор сессии: для id «уже существует». */
+    tenant: string | null;
+    /** Владелец новых строк по умолчанию (db.as(…, { owner })). */
+    owner?: string;
+}
+/** Чтение в транзакции плана — тот же построитель, что у цепочек. */
+export declare function readIn<T>(w: WriteCtx, steps: Step[], mods: ChainMods, mode: ReadMode, agg?: AggSpec): Promise<{
+    q: BuiltQuery;
+    res: T[];
+}>;
+/** Роль слота: имя роли записываемого класса или класс, который принимает ровно одна роль. */
+export declare function slotRole(reg: Registry, owner: ClassInfo, name: string): string;
+interface Segment {
+    /** Шаги сегмента; последний несёт глагол. */
+    steps: Step[];
+}
+/** Разрезать план: сегменты (…шаги + шаг с глаголом) и читающий хвост после последнего глагола. */
+export declare function splitPlan(steps: Step[]): {
+    segments: Segment[];
+    tail: Step[];
+};
+/** Результат плана: строки последнего глагола или чтение хвоста от них. */
+export type PlanResult = {
+    kind: 'rows';
+    rows: WriteRow[];
+    key: string;
+} | {
+    kind: 'read';
+    q: BuiltQuery | null;
+    res: unknown[];
+};
 /**
- * .purge({confirm}): ФИЗИЧЕСКИЙ hard-erase — сносит логически удалённые цели + всё поддерево (все версии).
- * Вся логика — в серверной purge() (двухфазность: живую цель не трогает; замыкание по links; SET LOCAL
- * отключает entity_delete → плоский снос без TM_SelfModified). JS лишь резолвит цели и зовёт функцию.
- * confirm: false → dry-превью (что сотрётся, БД цела); true → снос, возвращает снесённое ($deleted).
- * gate: DELETE-право на класс цели (aclWrite) — поддерево уже было DELETE-авторизовано при мягком удалении.
- * В отличие от .delete() (tombstone, обратимо) — необратимо, историю НЕ сохраняет.
+ * Исполнить план в транзакции w.q: сегменты по порядку, продолжение — от результата предыдущего
+ * глагола (create и upsert — по строке, остальные — от всех строк сразу); хвост — чтение от
+ * результата последнего глагола тем же построителем, что у цепочек.
  */
-export declare function purgeOp(ctx: Ctx, steps: Step[], mods: ChainMods, confirm: boolean): Promise<Row[]>;
-export type PlanMode = 'rows' | 'ids' | 'count' | 'paths' | 'versions' | 'agg';
+export declare function execPlan(w: WriteCtx, steps: Step[], mods: ChainMods, mode: ReadMode, agg?: AggSpec): Promise<PlanResult>;
 /**
- * Исполнить план целиком: все операции + финальное чтение — одна транзакция
- * (внутренняя, с ретраем transient; внутри db.begin() — транзакция пользователя).
- * Продолжение после операции: fan-out — каждый следующий сегмент исполняется от каждой
- * строки результата (контекст = строка); self-шаг (op сразу после op) пишет в те же строки.
- * После delete продолжение идёт от строк КЛАССА ЦЕЛИ (замыкание каскада шире).
+ * Очередь планов одной транзакцией. Подряд идущие простые вставки одного класса с ключом — одна
+ * многострочная вставка, подряд идущие upsert — тоже (повтор id режет группу: один оператор не
+ * меняет строку дважды); результат сопоставляется со входом по вычисленному id. Вставки класса без
+ * ключа уходят однострочными операторами одним конвейером: порядок строк в returning
+ * многострочной вставки не гарантирован, сопоставить не по чему.
  */
-export declare function runPlan(ctx: Ctx, steps: Step[], mods: ChainMods, mode: PlanMode): Promise<unknown>;
-/** План в очереди батча; steps обновляется по мере роста цепочки. */
-export interface BatchPlan {
-    steps: Step[];
-}
-export declare function executeBatch(ctx: Ctx, queue: BatchPlan[]): Promise<Row[][]>;
+export declare function execBatch(w: WriteCtx, plans: Step[][]): Promise<WriteRow[][]>;
 export {};