letopis 2.0.0 → 3.0.0

package/dist/watch.js

@@ -66,6 +66,8 @@ export class Subscription {
     start = null;
     /** Вызовы next() — по очереди: параллельные получают разные события (доработки после точки Б). */
     queue = Promise.resolve();
+    /** Выдано событий — для watch.stop. */
+    delivered = 0;
     constructor(ctx, opts) {
         this.ctx = ctx;
         this.opts = opts;
@@ -95,6 +97,10 @@ export class Subscription {
             this.wake?.();
         }, this.pollMs);
         this.timer.unref?.();
+        if (ctx.log?.wants('watch.start')) {
+            ctx.log.emit('watch.start', { op: 'watch', detail: { from: opts.from ?? 'now', classes: ctx.classes, batch: this.batch,
+                    pollMs: this.pollMs, signals: Boolean(ctx.onSignal) } });
+        }
     }
     /** Курсор подписки: позиция после последнего выданного события (или начальная точка) — с неё продолжают после перезапуска. */
     get cursor() {
@@ -128,6 +134,8 @@ export class Subscription {
         // пока события пачки не выданы, курсор подписки — позиция до пачки
         if (rows.length)
             this.given = encode(p);
+        if (rows.length && this.ctx.log?.wants('watch.fetch'))
+            this.ctx.log.emit('watch.fetch', { op: 'watch', rows: rows.length });
         for (const r of rows) {
             const row = toRow(r.row);
             const snap = keepSnap(p.snap, r.tx);
@@ -153,6 +161,7 @@ export class Subscription {
             if (this.buf.length) {
                 const ev = this.buf.shift();
                 this.given = ev.cursor;
+                this.delivered++;
                 return { value: ev, done: false };
             }
             if (this.closed)
@@ -167,6 +176,7 @@ export class Subscription {
                 }
                 catch (e) {
                     this.failure = e;
+                    this.ctx.log?.error(e, { op: 'watch' });
                     this.close();
                     throw e;
                 }
@@ -209,6 +219,9 @@ export class Subscription {
         if (this.closed)
             return;
         this.closed = true;
+        if (this.ctx.log?.wants('watch.stop')) {
+            this.ctx.log.emit('watch.stop', { op: 'watch', rows: this.delivered, detail: { cursor: this.cursor, ...(this.failure ? { failed: true } : {}) } });
+        }
         this.off?.();
         this.ctx.onClose?.(this);
         if (this.timer)

package/dist/write.d.ts

@@ -1,6 +1,6 @@
 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 { Executor, Tx } from './tx.js';
 import type { ChainMods, Row } from './types.js';
 /** Метка приращения; Symbol.for — маркер узнаёт и вторая копия пакета в процессе. */
 export declare const INC: unique symbol;
@@ -18,6 +18,53 @@ export declare function inc(by: number, opts?: {
     start?: number;
 }): IncMarker;
 export declare const isInc: (v: unknown) => v is IncMarker;
+/**
+ * Ожидаемая строка `expect` у `restore()` и `delete({ confirm: true })` (план 2.1, A1, A2): строка ответа или её `id`,
+ * `rev` (и `$action` превью удаления). Лишние поля строки не мешают.
+ */
+export interface Expected {
+    id: string;
+    rev: number;
+    /** У строки превью — что с ней будет; строку ответа (с любым $action) можно передать как есть. */
+    $action?: Row['$action'];
+}
+/**
+ * Опции delete() (3.0): без confirm — превью; `{ confirm: true, expect }` — удалить ровно показанное превью;
+ * `{ confirm: true, all: true }` — осознанно удалить текущий состав целей без сверки (и без фильтра). `{ confirm: true }`
+ * без expect и all — invalid_query (write.confirm_without_expect).
+ */
+export type DeleteOptions = {
+    confirm?: false;
+    all?: boolean;
+    expect?: undefined;
+    reason?: string;
+} | {
+    confirm: true;
+    expect: readonly Expected[];
+    all?: boolean;
+    reason?: string;
+} | {
+    confirm: true;
+    all: true;
+    expect?: readonly Expected[];
+    reason?: string;
+};
+/**
+ * Опции restore() (3.0): `{ expect }` — надгробия, которые видел пользователь (ответ delete() или withDeleted()), с
+ * `partial: true` — что можно; `{ all: true }` — осознанно вернуть все удалённые цели шага без сверки. Без expect и all —
+ * invalid_query (write.restore_without_expect), и для явных id.
+ */
+export type RestoreOptions = {
+    expect: readonly Expected[];
+    partial?: boolean;
+    all?: boolean;
+    reason?: string;
+} | {
+    all: true;
+    expect?: undefined;
+    partial?: false;
+    reason?: string;
+};
 /** Глагол плана; reason — причина изменения этого глагола (план 1.1, §2.1). */
 export type PlanOp = ({
     kind: 'create';
@@ -34,11 +81,21 @@ export type PlanOp = ({
     kind: 'delete';
     confirm: boolean;
     all?: true;
+    expect?: readonly Expected[];
 } | {
     kind: 'restore';
+    all?: true;
+    expect?: readonly Expected[];
+    partial?: true;
 }) & {
     reason?: string;
 };
+/**
+ * Данные create() и upsert() без ключей со значением undefined — как у патча update() (splitPatch): ключ undefined JSON
+ * не передаёт, а валидатор на TypeScript принимал его за поле не того типа (план 2.1, A12). Вложенные объекты — тоже;
+ * массивы, даты, маркеры и операторы — как есть.
+ */
+export declare function dropUndefined(data: Record<string, unknown>): Record<string, unknown>;
 /** Причина изменения: строка до 1000 символов без NUL (её не принимает set_config). */
 export declare function checkReason(v: unknown, where: string): string;
 /** Значение слота: id, список id, строка ответа или ленивая цепочка (в той же транзакции). */
@@ -66,6 +123,20 @@ export declare function splitPatch(patch: Record<string, unknown>): {
     rest: Record<string, unknown>;
     incs: IncSpec[];
 };
+/**
+ * Ошибка данных до записи у класса с правилами только для базы (`pattern`): валидатор на TypeScript нашёл не всё — полный
+ * список нарушений даёт база одним запросом (`validate_row`, план 2.1, A8), под точкой сохранения: неудача запроса
+ * (схема прежней ревизии) не ломает db.begin(), остаётся прежняя ошибка. Прочие ошибки — как есть.
+ */
+export declare function completeIssues(ctx: {
+    schema: string;
+    exec: Executor;
+}, e: unknown): Promise<unknown>;
+/**
+ * Блокировка строк в порядке id (lockedRead, updateOp — for no key update; deleteOp с expect — for update): id, которые
+ * удалось заблокировать.
+ */
+export declare function lockIds(q: Tx, S: string, ids: string[], mode?: 'no key update' | 'update'): Promise<Set<string>>;
 /**
  * Всё, что проверяется без базы, — до отправки первого оператора (§2.5). Фильтры шагов и поля sort() и агрегатов
  * (неизвестное поле — invalid_query, план 2.0, этап 3, п. 3) — precheckStep построителя; order и agg — модификатор и
@@ -92,6 +163,12 @@ export declare function readIn<T>(w: WriteCtx, steps: Step[], mods: ChainMods, m
 }>;
 /** Роль слота: имя роли записываемого класса или класс, который принимает ровно одна роль. */
 export declare function slotRole(reg: Registry, owner: ClassInfo, name: string): string;
+/**
+ * Почему цель restore не восстановить (второй раунд 2.1, A2, A3) — по записи журнала, которая идёт за последним
+ * надгробием: `restored` — за ним restore (объект уже восстановлен), `reissued` — create (id занял новый объект с тем же
+ * ключом), `changed` — прочее: удалён снова с другим номером версии, не удалялся вовсе, гонка.
+ */
+export type RestoreWhy = 'restored' | 'reissued' | 'changed';
 interface Segment {
     /** Шаги сегмента; последний несёт глагол. */
     steps: Step[];