letopis 1.4.2 → 3.0.0

package/dist/write.d.ts

@@ -1,6 +1,6 @@
-import { type ClassInfo, type Registry } from './registry.js';
+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';
@@ -26,30 +73,29 @@ export type PlanOp = ({
     kind: 'update';
     data: Record<string, unknown>;
     rev?: number;
+    all?: true;
 } | {
     kind: 'upsert';
     data: Record<string, unknown>;
 } | {
     kind: 'delete';
     confirm: boolean;
-} | {
-    kind: 'anonymize';
-    fields: string[];
-} | {
-    kind: 'reclass';
-    cls: string;
-    data?: Record<string, unknown>;
+    all?: true;
+    expect?: readonly Expected[];
 } | {
     kind: 'restore';
-} | {
-    kind: 'purge';
-    confirm: boolean;
-} | {
-    kind: 'rekey';
-    data: Record<string, unknown>;
+    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, строка ответа или ленивая цепочка (в той же транзакции). */
@@ -77,8 +123,26 @@ 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;
+/**
+ * Ошибка данных до записи у класса с правилами только для базы (`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 — модификатор и
+ * агрегат чтения за последним глаголом (терминал цепочки).
+ */
+export declare function precheckPlan(reg: Registry, steps: Step[], order?: string, agg?: AggSpec): void;
 export interface WriteCtx {
     reg: Registry;
     schema: string;
@@ -99,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[];