letopis 2.0.0 → 3.0.1

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,57 @@ export declare function inc(by: number, opts?: {
     start?: number;
 }): IncMarker;
 export declare const isInc: (v: unknown) => v is IncMarker;
+/**
+ * Ожидаемая строка `expect` у `restore()` и `delete({ confirm: true })`: строка ответа или её `id`, `rev` (и `$action`
+ * предпросмотра удаления). Лишние поля строки не мешают.
+ */
+export interface Expected {
+    id: string;
+    rev: number;
+    /** У строки предпросмотра — что с ней будет; строку ответа (с любым $action) можно передать как есть. */
+    $action?: Row['$action'];
+    /** Строка-сводка предпросмотра (`$action: 'hidden'`, 3.0.1): что будет со скрытыми правами строками. */
+    $hidden?: Row['$hidden'];
+    /** Строка-сводка предпросмотра: число скрытых правами строк. */
+    $count?: number;
+}
+/**
+ * Опции delete(): без confirm — предпросмотр; `{ confirm: true, expect }` — удалить ровно показанный предпросмотр;
+ * `{ confirm: true, all: true }` — осознанно удалить текущий состав целей без сверки (и без фильтра). `{ confirm: true }`
+ * без expect и all — invalid_query.
+ */
+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(): `{ expect }` — надгробия, которые видел пользователь (ответ delete() или withDeleted()), с
+ * `partial: true` — что можно; `{ all: true }` — осознанно вернуть все удалённые цели шага без сверки. Без expect и all —
+ * invalid_query, и для явных 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,14 +85,24 @@ 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, строка ответа или ленивая цепочка (в той же транзакции). */
+/** Значение шага роли: id, список id, строка ответа или ленивая цепочка (в той же транзакции). */
 export type SlotValue = string | string[] | {
     id: string;
 } | null | {
@@ -54,7 +115,7 @@ export interface Slot {
     op: 'set' | 'unset' | 'add' | 'remove';
     value: SlotValue;
 }
-/** Строка ответа записи (результат upsert — $upsert, превью удаления — $action — поля Row). */
+/** Строка ответа записи (результат upsert — $upsert, предпросмотр удаления — $action — поля Row). */
 export type WriteRow = Row;
 export interface IncSpec {
     path: string[];
@@ -66,6 +127,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 +167,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[];